224 lines
12 KiB
Markdown
224 lines
12 KiB
Markdown
---
|
|
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: `refund | replacement | compensation | warning_seller | ban_seller | no_action`. See `backend/src/models/Dispute.ts`.
|
|
|
|
### Escrow
|
|
|
|
> [!info] Definition
|
|
> The custodial period during which buyer funds are held by the platform (SHKeeper or the smart contract layer) after payment but before release to the seller. Escrow guarantees the seller will be paid if they deliver, and guarantees the buyer can be refunded if they do not. The defining feature of Amn.
|
|
|
|
### 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 — SHKeeper may deliver the same webhook several times if it does not receive a 200 quickly. Amn enforces idempotency in `PaymentCoordinator` and at the model level via unique constraints on transaction hashes.
|
|
|
|
### 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 buyer's choice of pay-in surface (SHKeeper invoice vs. Web3 wallet) is independent of how the payout will be sent.
|
|
|
|
### 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 the chosen amount, currency, expected wallet address (SHKeeper) or counterparty (DePay), and an expiry. Becomes a confirmed `Payment` once the chain or webhook confirms 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. Recorded as `Payment.direction: "out"`. Triggered by admin action after delivery is confirmed; implemented via SHKeeper's payout API (`shkeeperPayoutService.ts`).
|
|
|
|
### 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 as Amn's primary custodial pay-in / payout rail. Issues a fresh wallet address per invoice, watches the chain for incoming USDT, and emits a signed webhook on settlement. Lives at `https://pay.amn.gg` per `backend/TODO.md`. Integration code under `backend/src/services/payment/shkeeper/`.
|
|
|
|
### 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. USDT is the default for SHKeeper invoices; both are 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. SHKeeper webhooks (`/api/payment/shkeeper/webhook`) are the most important — they confirm pay-ins. All webhooks are HMAC-signed; verification uses `SHKEEPER_WEBHOOK_SECRET`. Failed verifications are dropped.
|
|
|
|
### 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.
|