---
title: Glossary
tags: [overview, glossary, definitions, terminology]
created: 2026-05-23
---

# Glossary

> [!info] How to read this page
> Terms are listed alphabetically. Where a term is also the subject of its own doc, the heading links there. When a term references another glossary entry, it is shown as plain bold rather than a wikilink — flip back here as needed.

---

### Admin

> [!info] Definition
> A user with `role: "admin"` and full read/write access to every part of the platform — moderation, payments, disputes, content. Created at boot via `backend/src/infrastructure/database/init-admin.ts`. See [[Roles & Personas]].

### Buyer (User)

> [!info] Definition
> A user with `role: "buyer"`. Posts **Purchase Requests** and accepts **Seller Offers**. The default role assigned at signup. UI label: "User".

### Category

> [!info] Definition
> A taxonomy node used to classify Purchase Requests and templates. Sellers can flag themselves as a preferred seller in a category. Backed by the `Category` model (`backend/src/models/Category.ts`); seeded via `seedCategories.ts`.

### Chat

> [!info] Definition
> A multi-party real-time conversation persisted in MongoDB (`Chat` model) and streamed over Socket.IO. Chats are scoped to a Purchase Request, a Dispute, or a direct support thread. Per-chat rate limiting is enforced by `chatRateLimiter.ts`.

### DePay

> [!info] Definition
> A drop-in Web3 payment widget (`@depay/widgets`) used on the frontend to let buyers pay directly from their own wallet on supported EVM chains. The transaction is signed in the wallet, broadcast to the chain, and verified server-side. See [[Payments Overview]].

### Delivery Code

> [!info] Definition
> A six-digit one-time code generated when a physical order ships. The buyer reads it to the courier (or the seller types it into the app at handoff) to confirm receipt and release escrow. Stored on `PurchaseRequest.deliveryInfo.deliveryCode` with `deliveryCodeExpiresAt` and a usage audit trail (`backend/src/models/PurchaseRequest.ts`).

### Dispute

> [!info] Definition
> A formal complaint opened by either party when a deal goes wrong. Creates a three-way chat (buyer, seller, admin) and a `Dispute` document with a structured `timeline[]`, `evidence[]`, and `resolution`. Categories: `product_quality | delivery_delay | wrong_item | payment_issue | seller_behavior | other`. Outcomes in the current model: `refund | replacement | compensation | warning_seller | ban_seller | no_action`. See `backend/src/models/Dispute.ts` and [[Dispute Flow]].

### Escrow

> [!info] Definition
> The custodial period during which buyer funds are held by platform-controlled custody infrastructure after payment but before release to the seller. The current primary path uses Request Network pay-in, per-payment derived destinations, transaction-safety checks, and an internal funds ledger. Future custody decentralization is tracked in [[PRD - Decentralized Custody and Smart-Contract Escrow Roadmap]].

### Idempotency

> [!info] Definition
> The property that the same request (identified by an idempotency key) can safely be retried without performing the underlying operation more than once. Critical for payment webhooks and release/refund confirmations. Amn enforces idempotency in `PaymentCoordinator`, Request Network delivery handling, pending-intent indexes, and ledger idempotency keys.

### JWT (Access / Refresh)

> [!info] Definition
> JSON Web Tokens issued by the auth service. **Access tokens** are short-lived and carried on every authenticated request in the `Authorization: Bearer` header. **Refresh tokens** are longer-lived, stored on the `User` document, and exchanged for a new access token without re-prompting credentials. Rotated on every refresh.

### Level

> [!info] Definition
> A user tier derived from accumulated points. Configured in `LevelConfig` (`backend/src/models/LevelConfig.ts`). Higher levels unlock perks such as reduced fees or higher-priority placement.

### Negotiation

> [!info] Definition
> The back-and-forth between a buyer and a seller after an offer is submitted but before it is accepted. Implemented as standard chat messages in the request's chat room. A purchase request enters the `in_negotiation` status when at least one offer exists and discussion is active.

### Notification

> [!info] Definition
> A platform event delivered to a user, either in-app (via Socket.IO to the user's personal room) or by email (`nodemailer`). Persisted as `Notification` documents so they can be read on subsequent sessions. Categories include `offer_received`, `payment_confirmed`, `dispute_update`, and more.

### Owner

> [!info] Definition
> The UI label for a **Seller**. They "own" a shop. Synonym; same underlying `role: "seller"`.

### Passkey

> [!info] Definition
> A WebAuthn credential bound to a device (platform or cross-platform). Replaces passwords for fast biometric login. Multiple passkeys per user supported (`User.passkeys[]` in `backend/src/models/User.ts:125`). See [[Authentication Flow]].

### Pay-in

> [!info] Definition
> Money flowing **into** escrow from the buyer. Recorded as `Payment.direction: "in"`. The current primary path is Request Network in-house checkout, with payment safety verified by webhook/reconciliation plus on-chain transaction checks.

### Pay-in Intent

> [!info] Definition
> The pre-authorisation record created when a buyer commits to paying but the funds have not yet arrived on-chain. Holds amount, currency, Request Network IDs/payment reference, in-house checkout metadata, and expected destination. Becomes a confirmed `Payment` only after webhook/reconciliation and transaction-safety checks approve settlement.

### Payment

> [!info] Definition
> A monetary transaction record. One `Payment` document covers a pay-in, payout, or refund. Carries `direction`, `provider`, `blockchain` metadata (network, tx hash, confirmations), buyer, seller, and the related purchase request and seller offer. See `backend/src/models/Payment.ts`.

### Payment Coordinator

> [!info] Definition
> A backend module (`backend/src/services/payment/paymentCoordinator.ts`) that serialises payment state transitions using Redis locks. Prevents the race condition where a webhook and a manual confirmation both try to flip the same payment to `paid`.

### Payout

> [!info] Definition
> Money flowing **out** of escrow to the seller's wallet. Triggered by release/refund orchestration after delivery confirmation or dispute resolution. The roadmap moves execution authority to Safe multisig/hardware signers before any custom smart-contract escrow pilot.

### Points

> [!info] Definition
> The loyalty currency. Earned for completed deals, verified referrals, and certain in-app actions. Spent on fee discounts or platform perks. Each grant or spend writes a `PointTransaction` row for full auditability (`backend/src/models/PointTransaction.ts`).

### Point Transaction

> [!info] Definition
> An immutable record of a single change to a user's point balance — credit or debit, with `reason`, `relatedEntity`, and timestamp. The audit trail for the points system.

### Preferred Seller

> [!info] Definition
> A seller a buyer can specify on a purchase request to direct the offer notification to a narrower audience. Listed in `PurchaseRequest.preferredSellerIds[]`. Other sellers may still see the request if it is public.

### Purchase Request

> [!info] Definition
> The buyer's brief — what they want to acquire, for how much, by when, and where to deliver. The originating document of every deal. Long status enum walking the entire lifecycle from `pending_payment` through `completed`. See `backend/src/models/PurchaseRequest.ts`.

### Referral

> [!info] Definition
> A signup attributed to an existing user via their unique `referralCode`. Triggered through the `/r/:code` short URL (`backend/src/app.ts:274`) which redirects to the signup page with the code pre-filled. Referrer earns points when the referred user completes qualifying actions.

### Referral Code

> [!info] Definition
> A short unique string on every user (`User.referralCode`) that identifies them as a referrer. Used in the `/r/:code` redirect.

### Request Template

> [!info] Definition
> A reusable, pre-configured purchase request that acts like an express checkout. Admin templates appear in a platform catalogue; seller templates are shop-scoped. Clicking "buy" on a template spawns a real `PurchaseRequest` with the template's defaults. See `backend/src/models/RequestTemplate.ts` and `frontend/template-request-feature.md`.

### Review

> [!info] Definition
> Post-completion feedback from one party about the other — star rating plus free-form text. Stored in the `Review` model. Aggregated onto the seller's shop profile.

### Role

> [!info] Definition
> The user's identity tier in the system: `"admin" | "buyer" | "seller"` (`backend/src/models/User.ts:94`). Drives middleware authorisation. Support is a special admin variant rather than a distinct role.

### Seller (Owner)

> [!info] Definition
> A user with `role: "seller"`. Submits offers on requests, runs a shop, receives payouts. Retains all buyer capabilities. UI label: "Owner".

### Seller Offer

> [!info] Definition
> A single bid attached to one Purchase Request — `price`, `deliveryTime`, `status` (`pending | accepted | rejected | withdrawn`), optional `validUntil`, optional attachments. See `backend/src/models/SellerOffer.ts`.

### Shop

> [!info] Definition
> A seller's public profile + storefront — name, banner, description, payout wallet, response-time SLA, working hours. Configured in `ShopSettings` and rendered at `/dashboard/shops/<id>`.

### SHKeeper

> [!info] Definition
> A self-hosted crypto payment processor used by older Amanat payment designs. Its docs remain for migration and historical context, but the current backend payment tree has moved to Request Network as the primary provider.

### Socket Room

> [!info] Definition
> A logical channel inside the Socket.IO server that scopes events to a subset of connected clients. Rooms used by Amn include `user-<id>`, `chat-<id>`, `request-<id>`, `seller-<id>`, `buyer-<id>`, `sellers`, `buyers`. See `backend/src/app.ts:79-179`.

### Status (Order)

> [!info] Definition
> The current point in a Purchase Request's lifecycle. Full enum: `pending_payment | pending | active | received_offers | in_negotiation | payment | processing | delivery | delivered | confirming | completed | cancelled | seller_paid`. Each transition emits a Socket.IO event and may trigger notifications.

### Support

> [!info] Definition
> A constrained admin persona dedicated to answering tickets and triaging disputes. Same role enum (`admin`) but with permission middleware that blocks destructive operations. Seeded as `support@amn.gg`.

### USDT / USDC

> [!info] Definition
> The two stablecoins Amn supports out of the box for pay-in and payout. Request Network token registry work covers USDC/USDT across supported EVM chains; both are also supported in offer pricing (`SellerOffer.price.currency` enum: `USD | EUR | IRR | USDT | USDC`).

### Webhook

> [!info] Definition
> An inbound HTTP POST from an external service notifying Amn of an event. The primary payment webhook is Request Network at `/api/payment/request-network/webhook`, signed with `x-request-network-signature`. Roadmap work puts durable ingress/replay in front of the backend while keeping backend signature verification and transaction-safety checks as the trust boundary.

### WalletConnect

> [!info] Definition
> An open protocol for connecting wallets to web apps via a QR code or deep link. Configured but **currently disabled** in `frontend/src/web3/config.ts` pending an SSR-compatibility fix; MetaMask is the active connector.

### Web3 Wallet

> [!info] Definition
> A user-controlled key store (MetaMask, hardware wallet, mobile wallet) that signs blockchain transactions. The frontend talks to wallets through Wagmi + Viem and the user keeps custody of funds right up to the moment of payment.

---

## See also

- [[Introduction]] — high-level project framing.
- [[System Overview]] — how the pieces connect.
- [[Roles & Personas]] — who uses what.
- [[Tech Stack]] — exact tool versions.
- [[02 - Data Models]] — schemas for every term defined above.
- [[04 - Flows]] — the lifecycle diagrams those terms appear in.
