nick-doc/00 - Overview/Glossary.md

title, tags, created

title	tags	created
Glossary	overview glossary definitions terminology	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.