Glossary
Terms are grouped by area. Where the dashboard, the API and the on-chain code use different names for the same thing, the entry lists all of them.
Installation and accounts
| Term | Meaning |
|---|---|
| Install | One docker compose project on one server, written to /opt/recvfund by the installer. It runs the API, the web app (dashboard and checkout page), Caddy, Redis and either a bundled or an external Postgres. One install serves one business with any number of projects. |
| Network type | Whether an install runs against mainnet or the test networks. Set as NETWORK_TYPE in /opt/recvfund/.env at install time. testnet means Solana devnet and Robinhood Chain testnet. It cannot be changed later without a reset, which removes the data. |
| Root account | The first account, created once at /signup. It has the owner role. There is exactly one owner; it cannot be removed or demoted. |
| Role | One of owner, admin, project-lead, project-manager or project-ops. Owners and admins see every project. The other roles see only the projects they are assigned to. See User management. |
| Project | One brand or store inside an install. A project has its own checkout branding, enabled currencies, API keys, webhook endpoints, payout limits, hot wallet assignment per chain family and merchant registration per chain. See Multi-brand projects. |
AES_ENCRYPTION_KEY | A key in /opt/recvfund/.env generated by the installer. It encrypts every secret stored in the database, including hot wallet private keys, webhook secrets and the SMTP password. If it is lost, those secrets cannot be recovered. |
| Site URL | The public origin of the install, for example https://pay.example.com. Used to build checkout URLs. Set at install time and editable under Settings. |
| Activity log | The record of every write request and every denied request, with the actor, path, status and a redacted payload. Shown under Settings. |
Chains and tokens
| Term | Meaning |
|---|---|
| Chain | A supported network, identified by a code: SOLANA or ROBINHOOD. Each chain exists once per network type. See Networks and tokens. |
| Chain family | The technology behind a chain: solana or evm. Hot wallets are created per family. |
| Currency | A token or native coin on one chain, for example USDC on Solana or USDG on Robinhood Chain. Each currency has a standard (native, spl or erc20), a token address (empty for native coins) and a decimals count. |
| Native coin | SOL on Solana and ETH on Robinhood Chain. Both are accepted as payment currencies and both pay transaction fees, so the hot wallet must hold some. |
| Stablecoin | A currency the install prices at exactly 1.00 USD: USDC, USDT and USDG. SOL and ETH are priced from CoinGecko. |
| RPC node | An HTTP endpoint the install uses to read from and send to a chain. Each chain has a pool of nodes. Reads try the preferred node first and fall back to the next node on failure. Signing and sending never fall back. See Node configuration. |
| Confirmations | The number of blocks (or, on Solana, the commitment level) a transaction needs before it counts. The chain default is 1 for Solana and 12 for Robinhood Chain; a project can override it. A transfer below the threshold is detected and adds no value to the payment until it is confirmed. |
| Explorer | The public block explorer for a chain. The chain catalog stores URL templates for transactions and addresses on it. |
On-chain program and registration
| Term | Meaning |
|---|---|
| Program, factory | The on-chain code recv.fund deploys once per network: the recvfund program on Solana and the RecvFundFactory contract on Robinhood Chain. Customer payments never call it. On Solana it holds the merchant accounts and performs sweeps; on Robinhood Chain the factory only creates merchant contracts and holds no funds. Each release ships its address (program ID or factory address) for every network where it is deployed, and the installation connects to it by itself after checking its code; Settings, Nodes shows the result. The earlier RecvFund registry contract and program ID G9u3a8P6T5RFsgQhjVC5Yw7oAUqURst5MQJi1rFVkzAt are superseded. |
Merchant contract (MerchantVault) | On Robinhood Chain, the merchant’s own contract, created by the merchant’s admin wallet through the factory in one transaction. It records the settlement wallet, sweeper, active flag, fee rate and fee collector, derives the customers’ deposit addresses and performs sweeps. It has no owner, no upgrade, no pause and no function that sends funds anywhere except the settlement wallet and the recorded fee collector. |
| Merchant registration | The on-chain record that makes a project a merchant on one chain: the Merchant account of the program on Solana, the merchant contract on Robinhood Chain. It holds a merchant id, an admin, a settlement wallet, a sweeper, an active flag, and the fee rate and fee collector fixed at registration. It is created by one transaction signed by the admin wallet. One registration exists per project per chain. The dashboard lists them under Wallets, Deposit wallets. See Merchant registration. |
| Merchant id | 32 random bytes generated by the server when a registration is prepared. It identifies the merchant on-chain and is part of every deposit address derivation. |
| Admin wallet, admin key | The browser wallet that signed the registration transaction. It is the only key that can change the settlement wallet, the sweeper or the active flag for that registration. Its private key never enters the server. |
| Settlement wallet, cold wallet | The address, registered on-chain, that receives every sweep minus the fee. The dashboard labels it “Cold wallet (settlement address)”. Only a transaction signed by the admin wallet can change it. |
| Sweeper | The key allowed to sweep deposit addresses for a registration. The server sets it to the assigned hot wallet at registration. The admin wallet can always sweep as well. |
| Active flag | A per-registration switch controlled by the admin wallet. It has no effect on chain; your server reads it and, while it is off, stops offering checkout on that chain. Sweeps are never affected, so funds at a deposit address can always be moved to the settlement wallet. |
| Fee collector | The wallet that receives the recv.fund fee. recv.fund sets the collector for new registrations; it is copied into each registration when it is created and never changes for that registration. |
| Fee, basis points | The percentage taken from each sweep, and only from sweeps; nothing is taken when a customer pays. It is stored in basis points (1 bps is 0.01%), copied into the registration when it is created, and never changes for that registration. The fee is the swept amount times the rate divided by 10,000, rounded down. The dashboard shows it as “Fee: N bps of each sweep” when you register and as “Fee for new registrations” under Nodes. |
| Fee cap | The 200 bps (2%) maximum, compiled into the program and the contracts. A rate above it cannot be set for new registrations or copied into a registration. |
| Fee redirect | If the fee collector cannot receive a fee during a sweep, the fee goes to the settlement wallet instead and the chain emits FeeRedirected; the sweep’s recorded fee is 0. No account recv.fund controls can block a sweep. |
Wallets and addresses
| Term | Meaning |
|---|---|
| Hot wallet | The one kind of private key the server holds. Generated or imported in the dashboard per chain family and stored encrypted with AES-256-GCM under AES_ENCRYPTION_KEY. It pays transaction fees for sweeps and sends payouts. A hot wallet is assigned to projects; each project has one assignment per family, and one wallet can serve several projects. There is no key export. See Hot wallet. |
| Deposit address | A permanent address per customer per chain, derived from the merchant registration. Every customer payment goes to it. On Solana it is a program-derived address with seeds deposit, the merchant account and the customer reference; token deposits go to that address’s associated token account per mint. On Robinhood Chain it is a CREATE2 address computed by the merchant contract from the customer reference. No private key for a deposit address exists anywhere. See Customer deposit wallets. |
| Customer | A record in a project with the merchant’s own customer id (customerID in the API), an email address and a random 32-byte customer reference. Customer ids are unique within a project. |
| Customer reference | The 32 random bytes assigned to a customer. Together with the merchant id it determines the customer’s deposit address on every chain. |
| Deposit forwarder | The minimal contract behind a Robinhood Chain deposit address. The merchant contract deploys it on the first sweep of that address, with gas paid by the hot wallet; the address is the same before and after deployment. It transfers only when its merchant contract instructs it to. |
| Associated token account (ATA) | On Solana, the token account that holds a specific SPL token for an owner address. Settlement, fee collector and deposit destinations for tokens are the ATAs of those addresses. The deposit ATA is closed on sweep and recreated by the next deposit. |
| Balance | What a deposit address or hot wallet holds right now, read from the chain on request. The dashboard shows amounts as decimal strings and a USD value; when a price is unavailable the USD value is empty rather than zero. |
Payments
| Term | Meaning |
|---|---|
| Payment, invoice | A request for a USD amount from a customer. Created by POST /api/v1/payment or as a payment link in the dashboard. It has a reference id, an optional merchant invoice id, an expiry, and a state. |
| Reference id | The public UUID that identifies a payment. It appears in the checkout URL (/payments?reference_id=...), in API paths and in every webhook. |
| Invoice id | An optional label the merchant attaches to a payment (invoiceID). It is echoed in webhooks as invoice_id. It is not unique and does not identify the payment; the reference id does. |
| Payment link | A payment created from the dashboard rather than the API. Same states, same checkout page, same webhooks. See Payment links. |
| Checkout page | The public page at /payments?reference_id=<uuid> served by your install. It shows the amount, the enabled currencies, the deposit address and QR code, and a wallet payment button. It polls payment status every five seconds. |
| Payment state | One of OPEN, PARTIALLY_FILLED, FILLED, OVER_FILLED or CANCELLED. The database uses the same names in kebab-case. |
| Fill tolerance | The absolute USD difference, default 0.01, within which a payment counts as FILLED. Below the tolerance it is PARTIALLY_FILLED; above it is OVER_FILLED. |
| Expiry | The time after which an OPEN payment becomes CANCELLED. Default 24 hours (payment.expiryHours); an explicit expiry can be given at creation. Partially filled payments do not expire automatically. |
| Quote | The exact token amount the checkout page asks for once the customer selects a currency. It is valid for payment.quoteTtlSeconds (default 300 seconds) or until the payment expires, whichever is sooner. |
| Wallet payment | A payment made from a connected wallet on the checkout page. The wallet signs one plain transfer of the quoted amount to the customer’s deposit address; no recv.fund contract or program instruction runs and no fee is taken. It is recorded as a deposit and credited to the payment that was being paid. |
| Deposit | A transfer into a customer’s deposit address, from a connected wallet at checkout or from any wallet or exchange. A transfer confirmed through the checkout page is credited to the payment that was paid; any other is matched to the open or partially filled payment whose current quote has the same currency and exact amount, otherwise to the customer’s newest open or partially filled payment, and with none eligible it is recorded as an unmatched deposit under the customer. The fee is deducted later, at sweep. |
| Unmatched deposit | A confirmed deposit with no eligible payment to credit. It stays in the customer’s history and in the ledger and is swept like any other balance. |
| Transaction (ledger) | Every on-chain transfer the install has verified, with hash, amounts, USD value at detection time and status detected, confirmed or orphaned. This release records every transfer with kind deposit; the kind checkout-pay belonged to the superseded program payment path and is not written any more. |
| Watcher | The set of schedulers in the API that discover deposits and recheck confirmations. They store their progress in the database so they resume where they stopped. |
| Missed payment report | A transaction hash you submit under Payments, Missed payments when a payment was not credited. The worker verifies the transaction on-chain and credits it through the normal path, or rejects it with a reason. |
| Test payment | A payment on a testnet install. The checkout page labels it and the checkout URL carries test=true. |
Sweeps
| Term | Meaning |
|---|---|
| Sweep | Moving the whole balance of one currency at one deposit address to the settlement wallet, through the program on Solana or the merchant contract on Robinhood Chain. The fee is deducted at the registration’s fixed rate and sent to the registration’s fee collector in the same transaction. The transaction is signed by the project’s hot wallet. See Sweeps and Funds sweeping. |
| Activation threshold | sweep.activationUsd, default 5 USD. A deposit balance below it is not eligible for an automatic sweep. Manual sweeps ignore it. |
| Sweep triggers | The conditions that start an automatic sweep for a project and chain: amount (sweep.amountUsd, default 50 USD across eligible balances), count (sweep.addressCount, default 25 eligible addresses) or time (sweep.intervalMinutes, default 1440). Precedence is amount, count, then time. |
| Manual sweep | A sweep queued from the dashboard for selected addresses and currencies. It bypasses the activation threshold, the triggers and the automatic-sweep switch. |
| Sweep status | pending, sent, confirmed or failed. sent means a broadcast was attempted; confirmed means the sweep’s DepositSwept event was verified. |
Payouts
| Term | Meaning |
|---|---|
| Payout | A transfer from the project’s hot wallet to an address, in token units. It is a direct transfer and does not go through the program or any recv.fund contract. Created in the dashboard or by POST /api/v1/withdrawal/merchant. See Payouts. |
| Address book | Saved payout recipients per project: name, email, chain and address. A payout snapshots the recipient at creation, so later edits cannot redirect it. |
| Payout limits | USD limits per project, evaluated per recipient email: minimum, hourly, daily and auto-approve maximum. |
| Approval | Dashboard payouts always require an installation administrator to enter a one-time code sent by email. API payouts within the project’s auto-approve limit are approved automatically; above it they wait for the same approval. SMTP must be configured. |
| Payout status | pending-otp-verification, pending-approval, pending, initiated, sent, processed, failed, rejected or cancelled. |
| Idempotency key | An optional value (Idempotency-Key header) on payout creation. Repeating the same request with the same key returns the original payout; the same key with changed fields is rejected. |
Integration
| Term | Meaning |
|---|---|
| API key | A 32-character hexadecimal key that authenticates a project’s requests to the merchant API in the API-Key header. Created under Developers and shown once; only a hash is stored. Keys are rate limited per key. See API keys and API integration. |
| Webhook endpoint | A URL in a project that receives a signed JSON POST on payment creation, payment state changes, confirmation progress and payout state changes. Each endpoint has a secret, shown once at creation or rotation. See Webhooks. |
| Webhook signature | The X-Recv-Signature header: sha256= followed by the HMAC-SHA256 of the raw request body, keyed with the endpoint secret. X-Payram-Signature carries the same value. |
| Delivery | One attempt series for one event to one endpoint, identified by X-Recv-Delivery. Failed deliveries are retried on a fixed schedule; the last attempt and next attempt time are shown under Developers. |
| Event type | The X-Recv-Event header value: payment.confirming, payment.filled, payment.partially-filled, payment.over-filled, payment.cancelled, and payout.<status> for payouts. |
Last updated on