54 KiB
SimpleX names in the store service: architecture and flows
With the names part of the SimpleX store service, added by PR 7979, SimpleX names are sold on simplex.domains and registered on chain. A name is paid by card (Stripe), by Bitcoin or Monero (BTCPay), with a prepaid code, or from the balance of an earlier order. Each order is checked against the names contracts; the service then commits the order's commitment, relays the owner's acceptance of the terms and registers the name. Every transaction is signed with the service's registrar key, and the owner signs messages that the service verifies. One process per database runs the web API, the payment poller, the names worker, the transaction sender, the record edits lane and the chat core. The badge sale existed before this PR and is shown only where parts are shared with it.
Related docs: README | Names overview | Deployment
Source: Service.hs | Web/Server.hs | Web/Names.hs | Web/Names/ | Poller.hs | Orders.hs | Names/ | Group.hs | Config.hs
Table of contents
- System diagram
- Parts
- Scenarios
- A name ordered and paid by card or crypto
- A paid order registered on chain
- A prepaid name code issued and spent
- A name searched, and a link previewed
- A register transaction that fails
- A failed order queued again or moved
- An owner's orders found
- A balance spent on another name
- Late crypto credited
- A balance refunded by support
- A registered name's links edited
- Service start
1. System diagram
flowchart LR
ops["Operators<br/>support, group admins"]
page["Names page<br/>simplex.domains in the browser"]
pay["BTCPay and Stripe"]
subgraph proc["simplex-store-service: one process per database"]
web["Web API<br/>/api, /webhooks, site files"]
poller["Poller<br/>invoice reads, settlement,<br/>expiry, late credits"]
worker["Names worker<br/>commit, acceptance relay, register"]
edits["Record edits lane"]
sender["Sender<br/>signs with the registrar key"]
chat["Chat core<br/>bot address, managed group,<br/>link profile reads"]
end
cli["Console<br/>--run-cli, service stopped"]
db[("PostgreSQL<br/>chat schema and service tables")]
eth["Ethereum node<br/>names contracts"]
smp["SMP servers<br/>through an SMP proxy"]
git["git.simplex.chat<br/>terms texts"]
page -->|"/api calls"| web
page -.->|"card or crypto payment"| pay
pay -->|"signed webhooks"| web
web -->|"create, cancel invoice"| pay
web -->|"read hints"| poller
poller -->|"read, list, cancel, rates"| pay
poller -.->|"status published"| web
worker <-->|"versions published"| web
web -->|"link edit"| sender
worker -->|"commit, acceptance, register"| sender
edits -->|"resend"| sender
sender -->|"signed transactions"| eth
proc -->|"eth_call, blocks, receipts"| eth
proc -->|"all service state"| db
web -->|"terms text"| git
web -->|"link profiles"| chat
chat <-->|"link data, group messages,<br/>badge requests"| smp
ops -->|"group commands"| smp
ops -->|"console commands"| cli
cli -->|"codes, refunds"| db
eth ~~~ git
How a request flows:
- The page calls
/api/*on its own origin. The API and both webhooks are answered on every listener port. Withserve_webapp = onthe names site is also served on the names port; with it off, as the template sets, Caddy serves the exported sites and proxies/api/*tobadges_port. Caddy is configured outside this repository (Web/Server.hs:124-151,Config.hs:505-514,store_service.ini.example:8-11,README.md:702-795). - A route is matched, its method checked, one token of its per-client limit taken (webhooks and site files take none), then its handler run (
Web/Names.hs:46-51,Web/Http.hs:209-222). - An order is checked against the contracts with
eth_call, a provider invoice is created, and the order is written with its invoice in one transaction (Web/Names/Orders.hs:86-173). - On a webhook only a read is queued. The poller reads the provider and settles the invoice in one transaction; a paid order is moved from
unpaidtoqueued(Web/Server.hs:500-554,Poller.hs:248-263,Orders.hs:95-213). - After each commit the new invoice status or registration version is published to in-memory watches, and the held long polls and worker threads waiting on them resume (
Orders.hs:106-117,Waiters.hs:24-84,Names/Phases.hs:23-65). - The names worker scans the database every 5 s and follows each order in
queued,committing,committedorregisteringin a thread of its own (Names/Worker.hs:82-84,Names/Worker.hs:115-126). - Every transaction is sent through the sender: dry run, nonce, fees, EIP-1559 signature with the registrar key, a saved row, then broadcast. Receipts are followed every 4 s to the confirmation depth (
Names/Sender.hs:107-131,Names/Sender.hs:151-226). - A link edit is submitted to the sender on its request's thread, and pending edits are settled by the record edits lane every 4 s (
Names/Records.hs:156-263,Names/Records.hs:265-302). - Link profiles are read through the chat core's connect plan, and the link data through SMP servers (
Names/Profiles.hs:269-274,Chat/Library/Internal.hs:1723-1726). - Operators issue and revoke codes in the managed group while the service runs. In the console, a separate run of the same binary while the service is stopped, they issue and revoke codes, record refunds and close failed paid orders (
Group.hs:263-300,Main.hs:25-28,Service.hs:414-433). - One process runs per database: a PostgreSQL advisory lock is held on a connection of its own for the whole run (
Store/Migrate.hs:46-58).
2. Parts
| Part | Role | Source |
|---|---|---|
| Startup | store_service.ini is parsed, the database lock taken, and the node's chain id and the issuer key checked; then the chat core is started. In its callback the providers, the names environment and the web environment are built, the sites exported, the managed group resolved, and all lanes started together. Without --service-config only the chat side and the badge request lanes run. |
Main.hs:15-28, Service.hs:280-370 |
| Web API | Warp listeners on [listener] host: badges_port (8080) always, names_port (8081) with [names] and serve_webapp = on. /api/* and both webhooks are answered on every port. Per-client limits a minute: read 60, search 30, preview 20, code 10, records 10, create 5, find 5. At most 500 long polls are held at once, each up to 30 s. |
Web/Server.hs:121-151, Web/Server.hs:562-585, Config.hs:505-514, Web/Names.hs:28-51, Web/Http.hs:109-154 |
| Order handlers | An order is placed in one of three ways: a paid invoice, a prepaid code, a spend of another order's balance. The owner's signature, the timestamp, the duration, the terms and an available name are checked, then the chain price for a paid or spent order and the balance for a spend. The order is written in one transaction, in which the same wallet's overdue orders for that name are closed. | Web/Names/Orders.hs:86-306, Names/Orders.hs:201-310, Names/Balances.hs:79-106 |
| Registration and owner handlers | The registration view, held on its version; the reveal; Try again; find by the owner's signature; a move to another name. | Web/Names/Registration.hs:45-140, Web/Names/Owner.hs:44-152, Names/Reveal.hs:103-145, Names/View.hs:52-112 |
| Search handlers | Name status, price, terms, and records with link profiles; the terms text; the link preview. These handlers only read. | Web/Names/Search.hs:53-154, Names/Profiles.hs:236-274 |
| Poller | One loop. A pass is run every waiting_seconds (3) while a page holds an invoice poll, else every idle_seconds (60), and webhook read hints are served between passes. Invoices are settled, overdue ones expired 10 minutes past their window, late money credited, and unpaid orders deleted daily, 30 days after their invoice expired. |
Poller.hs:62-76, Poller.hs:148-168, Poller.hs:559-598, Orders.hs:95-275, Names/LateCredits.hs:50-72 |
| Names worker | A thread is started by a scan every 5 s for each order in queued, committing, committed or registering: commit, wait for the reveal, terms acceptance relay, register, and the outcome judged from chain state. A daily sweep releases the codes of code orders failed for 30 days. |
Names/Worker.hs:115-401, Names/Worker.hs:503-522 |
| Sender | Signs with [chain] service_key, the only signer of that key. Per transaction: dry run, nonce, fees within max_fee_per_gas, EIP-1559 signature, a saved row, broadcast. Every 4 s: receipts followed to confirmations (default 3), an unknown transaction rebroadcast, and one unmined after 36 s replaced with higher fees when the market's fees have passed its own, within max_fee_per_gas. |
Names/Sender.hs:107-283 |
| Record edits relay and lane | Owner-signed link edits, each relayed as one resolver transaction through the sender, within record_edits_per_year and 10 an hour per name. Pending edits are settled by the lane every 4 s. |
Names/Records.hs:112-366, Web/Names/Records.hs:34-86 |
| Contracts reader and chain client | One JSON-RPC client to [chain] rpc_url, 10 s per call, redirects refused. Typed eth_call reads; the name policy address, the registrar constants and the commitment ages kept once read; terms texts fetched once per hash. |
Names/Contracts.hs:137-379, Names/Chain.hs:112-305 |
| In-memory coordination | Waiters: invoice status and payments. Phases: registration versions. Locks: one writer at a time per label hash, prepaid code and balance. Read hints: up to 256 webhook reads queued for the poller. | Waiters.hs:14-91, Names/Phases.hs:15-65, Names/Turns.hs:3-69, Poller.hs:88-108 |
| Chat core | The SimpleX chat controller with the bot user: the bot address for badge requests, the managed group's messages, and connect plans for link profiles. Every chat event is read from outputQ by one reader. |
Service.hs:293-313, Service.hs:636-645, Names/Profiles.hs:269-274 |
| Badge request lanes | Badge requests on the bot address, present before this PR: three lanes, each answer sent as APISendServiceResponse. |
Service.hs:572-657 |
| Group lane | With [group]: one managed group. /issue and /bulk are taken from moderators, /revoke and name codes from admins. A name code command is refused once the name codes created in the last 24 hours, console ones included, would pass 100. |
Group.hs:87-304, Group/Command.hs:59-73, Group/Command.hs:216-220 |
| Console | The same binary under --run-cli, while the service is stopped: the terminal chat and the badge request lanes only, with //issue, //issue name, //revoke, //refund and //close. //close reads the chain through a client of its own, made at start with [names]. |
Main.hs:25-28, Service.hs:382-538 |
| PostgreSQL | One database (BADGE_DB_CONN) with the chat core's schema and the sx_badge_service_ tables. Names tables: prepaid codes, registrations, balances, name invoices, late credits, record edits and their changes, transactions. Partial unique indexes admit one active order (live = 1) per commitment and per owner and label hash. |
Store/Postgres/Migrations.hs:276-473, compose.yml:16 |
| Names page | simplex.domains, in the submodule apps/simplex-domains, outside this checkout. /api/* is called on its own origin, and the owner's EIP-191 and EIP-712 signatures are sent from it. |
.gitmodules:4-7, Web/Names.hs:28-44 |
| BTCPay | Bitcoin and Monero invoices through Greenfield: create, read, list, cancel (status Invalid), store rates; webhooks signed with BTCPay-Sig. |
Providers/BTCPay.hs:267-367, Providers/BTCPay.hs:524-538, Providers/BTCPay.hs:555-578 |
| Stripe | Card PaymentIntents: create with an Idempotency-Key, read, list, cancel, also after 3 declined charges; webhooks signed with Stripe-Signature, within 15 minutes. |
Providers/Stripe.hs:101-302 |
| Ethereum node and names contracts | [chain] rpc_url: https, or http to a node on loopback. Controller, sponsor, base registrar and resolver are set in [chain]; the registry is read from ens(), the name policy from namePolicy(). The registrar key's USD allowance on the sponsor is raised outside the service with setRegistrarAllowance; on an InsufficientAllowance revert the order waits and an error is logged. |
Config.hs:186-198, Config.hs:698-703, Names/Contracts.hs:150-220, Names/Worker.hs:341 |
| SMP servers and proxy | Hold the bot address, the group's queues and the data of buyers' short links. Private routing for unknown servers, with a protected fallback, is preset by terminalChatConfig. |
Chat/Terminal.hs:41-63, Chat/Library/Internal.hs:1723-1726 |
| git.simplex.chat | Hosts the terms files the name policy links to, at a fixed commit, with the sha256 in the link. A loopback link is taken only on chain 31337. | Names/Contracts.hs:229-290 |
Deployment, the gas key and Caddy are described in the README and in scripts/store-service.
3. Scenarios
Participants:
| Letter | Participant |
|---|---|
| P | the names page in the buyer's browser, which sends the owner's signatures |
| W | the Web API: the Warp listeners and their handlers |
| D | PostgreSQL |
| E | the Ethereum node with the names contracts |
| V | the payment provider: BTCPay or Stripe |
| L | the poller |
| K | the names worker |
| S | the sender |
| R | the record edits lane |
| C | the chat core, or the console under --run-cli |
| M | SMP servers, reached through an SMP proxy |
| G | git.simplex.chat |
| O | an operator: support or a group admin |
| B | the buyer |
| U | the startup code: Main.hs and storeService |
Terms used in the diagrams:
- A lock is held in the process: one request or lane at a time per name (its label hash), prepaid code or balance (
Names/Turns.hs:3-69). - A read hint asks the poller to read one invoice at the provider before its next pass (
Poller.hs:88-108). - A lane is a thread that runs for the whole life of the process (
Service.hs:301-313,Service.hs:366-370). IDis a registration or invoice id,SOURCEthe registration id of the order whose balance pays,LABELHASHthe keccak256 of the label,REFERENCEan invoice id or a registration id. A signed order isowner,labelHash,length,duration,commitment,sealed,terms,timestampandsignature(Names/Orders.hs:150-169).
3.1 A name ordered and paid by card or crypto
A signed order is turned into an open invoice at the provider and a registration in phase unpaid, which is moved to queued when the payment is settled.
sequenceDiagram
participant P as Names page
participant W as Web API
participant D as PostgreSQL
participant E as Ethereum node
participant V as BTCPay or Stripe
participant L as Poller
P->>W: POST /api/invoice: kind name, method, price, signed order
W->>W: owner's EIP-191 signature checked, name lock taken
W->>D: identical earlier order looked up
W->>E: eth_call: terms of the name's kind, name status, rentPriceUSD
W->>V: create invoice for the price
W->>D: one transaction: invoice open, registration unpaid
W-->>P: 200 invoice view: clientSecret, or address and cryptoAmount
P->>W: GET /api/invoice/ID with wait and seenVersion, held up to 30 s
P->>V: card payment with the clientSecret, or crypto to the address
alt webhook
V->>W: POST /webhooks/btcpay or /webhooks/stripe, signature verified
W->>L: read hint with the provider reference
else no webhook
Note over L: next pass, every 3 s while a page holds a poll, else 60 s
end
L->>V: read invoice
L->>D: one transaction: payment row, invoice paid, registration queued
L-->>W: status and version published after the commit
W-->>P: held poll answered: paid, phase queued
Notes:
- The checks are run in the contract's order: timestamp within 600 s, duration (paid years plus the free days until
term_start), current terms, a name available on chain and not inregisteringhere, then the chain price equal to the order's (Web/Names/Orders.hs:104-118,Names/Orders.hs:266-310). Refusals are listed inWeb/Names/Orders.hs:344-357. - The terms text is fetched from git.simplex.chat on the first use of its hash and checked against the sha256 in its link; while it cannot be read, the order is answered
503 terms_unavailable(Names/Orders.hs:284-291,Names/Contracts.hs:229-258,Web/Names/Orders.hs:356). - The name lock is held across the provider call, and the answer is sent after it. Overdue unpaid orders of the same wallet and name are closed in the order's transaction (
Web/Names/Orders.hs:76-100,Names/Orders.hs:207-243). - When the order is not written, its provider invoice is cancelled. Provider checkouts are capped at 30 a minute for all clients together (
Web/Names/Orders.hs:139-173,Web/Http.hs:151-154). - Stripe is sent
metadata[order]=name:0x<order hash>and anIdempotency-Key; BTCPay is sent the amount, the currency and the checkout settings (Providers/Stripe.hs:240-269,Providers/BTCPay.hs:303-339). - On a webhook only a read is queued, and 200 is answered (
Web/Server.hs:500-554). - An open invoice without money can be cancelled with
POST /api/invoice/ID/cancel: the provider is told first, then the row is expired and the order closed (Web/Server.hs:358-381,Orders.hs:244-263). - Unpaid: 10 minutes past the expiry the poller's sweep expires the invoice and closes the order, after it cancels a Stripe intent; BTCPay expires its own invoice. The unpaid order is deleted 30 days after the expiry (
Poller.hs:62-76,Poller.hs:295-345,Orders.hs:265-275,Providers.hs:96-100). - Under
codes_only = onthis route is refused with403 codes_only(Web/Names/Orders.hs:88).
3.2 A paid order registered on chain
The names worker commits the order's commitment, waits for the page's signed reveal, relays the terms acceptance and registers the name.
sequenceDiagram
participant P as Names page
participant W as Web API
participant K as Names worker
participant S as Sender
participant E as Ethereum node
participant D as PostgreSQL
Note over K,D: a scan every 5 s starts a thread for the queued order
K->>E: commitments(commitment) is 0
K->>S: commit(commitment) to the controller, phase committing
S->>E: dry run, nonce, fees, signed, saved, eth_sendRawTransaction
S-->>K: receipt at the confirmation depth (default 3)
K->>D: phase committed, reveal window set
P->>W: GET /api/registration/ID, held while the version is unchanged
W-->>P: committed, intentNonce, the terms acceptance to sign
P->>P: owner signs RegisterName and the terms acceptance (EIP-712)
P->>W: POST /api/registration/ID/reveal: label, secret, links, signatures
W->>E: sponsor nonce, current terms, policy nonce
W->>D: reveal stored, version published
K->>S: acceptance relayed to the name policy
Note over K: register waits for the relay and for revealAfter
K->>S: registerWithCredit to the sponsor, phase registering
S-->>K: register receipt with status 1 at the depth
K->>D: phase registered, expiresAt read at the confirmed block
Note over P,W: the held GET answers registered with registerTx and expiresAt
Notes:
- Every transaction here is sent through the sender as the commit is, with value 0 and its gas paid by the registrar key; each kind is sent at most 5 times per order, moves included (
Names/Chain.hs:199-214,Names/Worker.hs:428-449). By the code comments and the log line of anInsufficientAllowancerevert, the rent is spent from the registrar key's allowance on the sponsor (Names/Contracts.hs:179-181,Names/Worker.hs:341). RegisterNameis signed in the EIP-712 domainSimplexSponsor, the acceptance inSimplexNamePolicy, asAcceptGeneralTermsorAcceptCommunityTerms(Names/Registration.hs:80-111).- The reveal is checked in the contract's order: the label, its hash and length, at most one link per key, the commitment rebuilt from the stored owner, duration and default resolver; the intent's deadline not before
revealBefore, its signer and the sponsor nonce; the acceptance against the current terms and policy nonce; the links' kinds last (Names/Reveal.hs:103-145). - A reveal whose link is not a short link of its record's kind is answered
400 invalid_link, and the order is markedlinksRefused. The links are part of the commitment, so only a move (3.6) continues the order (Web/Names/Registration.hs:95-109,Names/Orders.hs:315-320). - The acceptance relay is
commitUnderGeneralTermsWithSigorcommitUnderCommunityTermsWithSig. It is sent as soon as the reveal is stored, without waiting forrevealAfter, whilerevealBeforehas not passed, unless the policy already holds that acceptance. The register is sent after the relay settles andrevealAfterhas passed (Names/Worker.hs:254-272). - The links are set by
setTextcalls forsimplex.contactandsimplex.channelin the register's data (Names/Registration.hs:212-235). - Without a reveal by
revealBeforethe order is setfailedwith "The name was not signed in time" (Names/Worker.hs:251-253,Names/View.hs:145-152). - After a restart every phase is resumed from the stored order and the sender's saved transactions (
Names/Sender.hs:123-131,Names/Worker.hs:6-8).
3.3 A prepaid name code issued and spent
An operator issues a code good for one name. The buyer's order with it is queued without an invoice. Under codes_only = on, a code is the only way to order a name.
sequenceDiagram
participant O as Operator
participant C as Chat core or console
participant D as PostgreSQL
participant P as Names page
participant W as Web API
participant E as Ethereum node
alt console, with the service stopped
O->>C: //issue name 6 years 5
else managed group, admins only
O->>C: /issue name 6 years 5, a group message
end
C->>D: random code, only its SHA-256 stored with length and years
C-->>O: Code: SN6-..., shown once
Note over O,P: the code reaches the buyer outside the service
P->>W: POST /api/code/check: code
W->>D: code read by its SHA-256
W-->>P: 200: minLength, years, state
P->>W: POST /api/name/register: signed order and code
W->>D: code read by its SHA-256
W->>W: owner's signature checked, name lock taken
W->>D: identical earlier order looked up
W->>E: terms of the name's kind, name status
W->>D: under the code's lock: registration queued with price 0, code reserved
W-->>P: 200: registrationId
Note over W,D: the names worker registers it as in 3.2
Notes:
- Only the code's SHA-256 is stored, so a code not copied when shown cannot be recovered (
Names/Codes.hs:147-159).unpaidname codes are refused in the console (Service.hs:535-543). - In the group,
/issueis taken from moderators and above, a name code from admins. A name code command is refused once the name codes created in the last 24 hours, console ones included, would pass 100; the console has no cap (Group/Command.hs:59-73,Group.hs:289-294,Service.hs:421-422). - A code order is checked for the timestamp, the duration, the terms and an available name; its years are the code's, 2 for a community name (
Web/Names/Orders.hs:216-222,Names/Community.hs:54-59). - The code is spent when the name is registered, released when the order is set
taken, and kept for 30 days with a failed order for Try again, then released by the daily sweep (Names/Orders.hs:397-400,Names/Worker.hs:361-365,Names/Worker.hs:503-522). - A name code is withdrawn by
//revokeunless it is spent; a code an order already holds stays usable by that order (Names/Codes.hs:162-173,Names/Codes.hs:78-88). - Under
codes_only = onthe names site'sindex.htmlis served withcontent="codes", and paid orders and spends are answered403 codes_only(Web/Server.hs:168-174,Web/Names/Orders.hs:88,Web/Names/Orders.hs:240).
3.4 A name searched, and a link previewed
A search is answered with the name's state: available with its price and terms, reserved, or registered with its records and their profiles.
sequenceDiagram
participant P as Names page
participant W as Web API
participant D as PostgreSQL
participant E as Ethereum node
participant G as git.simplex.chat
participant C as Chat core
participant M as SMP servers
P->>W: GET /api/name/LABELHASH?length=N
W->>D: an order of this label hash in phase registering?
W->>E: within 10 s: nameExpires, communityNames, then owner or reservedNames
alt available
W->>E: rentPriceUSD, generalTermsLink, communityTermsLink
W->>G: terms text, once per hash, sha256 checked
W-->>P: available: price, years, termStart, terms, community
else registered
W->>E: records simplex.contact and simplex.channel, resolver nonce
W->>C: APIConnectPlan per link, 3 s each, after the chain reads
C->>M: short link data, unless the link is in the chat database
W->>D: record edits of the last 365 days
W-->>P: registered: entities, records, owner, recordEdits, expiresAt
end
P->>W: POST /api/link/preview: link
W->>C: the same profile read, under the preview limits
W-->>P: type, kind, displayName, image, profile
Notes:
- Only the label's hash and length are sent (
Web/Names/Search.hs:53-57). 30 a minute per client are allowed for searches and terms reads together; chain reads are run for at most 16 searches at once, for all clients together, and a 17th is answered429(Web/Names.hs:34-36,Web/Http.hs:128-149). - The owner and resolver are read from the registry for a name registered or in its grace period (
nameExpiresplusGRACE_PERIODnot before the latest block's time); for any other namereservedNamesis read (Names/Contracts.hs:149-162). - A name shown available on chain while an order here is in
registeringis answeredregisteredwith no entities; a reserved name is answeredreserved(Web/Names/Search.hs:66-72,Web/Names/Search.hs:97-98). - Records, their nonce and the edits left are read only for a name on the default resolver, and at most 5 links of each record (
Names/Contracts.hs:164-177,Web/Names/Search.hs:99-130). - A link whose host is, or resolves to, a non-public address is refused before it is read, and each DNS lookup is run in a thread of its own. Profiles are kept 600 s; 4 fetch slots are used by searches and 2 by previews (
Names/Profiles.hs:83-95,Names/Profiles.hs:326-371). - Private routing for unknown servers, with a protected fallback, is preset by
terminalChatConfig(Chat/Terminal.hs:59-63); the routing itself is implemented in simplexmq. GET /api/terms/HASHis answered with the text and link of either current terms link (Web/Names/Search.hs:141-154).
3.5 A register transaction that fails
After a register transaction reverts, the order is judged from chain state: its reveal is cleared for the page to sign again, it waits, it is set taken with its price kept as a balance, or it is set failed.
sequenceDiagram
participant K as Names worker
participant S as Sender
participant E as Ethereum node
participant D as PostgreSQL
K->>S: registerWithCredit to the sponsor
S-->>K: dry run reverted, or mined with status 0
K->>E: registered after all? ownerOf and nameExpires at the confirmed block
alt InvalidNonce, TermsNotAccepted or TermsMismatch from the dry run
K->>D: reveal cleared, phase stays committed, the page signs again
else InsufficientAllowance
K->>K: error logged, retried every 15 s
else name taken at the latest block and at the confirmation depth
K->>D: phase taken, a paid order's price kept as its balance
else name available
K->>D: phase failed, error "The name could not be registered"
end
Notes:
- Whether the name was registered after all is checked first: on a register mined with status 1, or with the name held by the owner at the confirmation depth, the order is set
registered(Names/Orders.hs:365-400,Names/Worker.hs:329-336). - An
InsufficientAllowancerevert waits for the registrar key's allowance on the sponsor to be raised outside the service (Names/Worker.hs:341). - On
CommitmentTooNewthe register is retried 1 s later. While the name is taken only above the confirmation depth, or is reported gone by the dry run whileavailable(label)is true, the order is retried every 15 s (Names/Worker.hs:340-352). - A code order set
takenhas its code released instead of a balance credited (Names/Worker.hs:361-368).
3.6 A failed order queued again or moved
A failed order is queued again by Try again, or moved to another name; both first check whether its name was registered after all.
sequenceDiagram
participant P as Names page
participant W as Web API
participant E as Ethereum node
participant D as PostgreSQL
alt Try again
P->>W: POST /api/registration/ID/retry
W->>E: registered after all? reveal valid for the nonce and window?
W->>D: phase queued, failure cleared, reveal kept or cleared
W-->>P: 200 the order's view: queued, or registered after all
else another name
P->>W: POST /api/registration/ID/name, signed new name
W->>E: registered after all? refused after 5 sends of a kind
W->>E: terms, name available, a paid order's rentPriceUSD at most its price
W->>D: under both names' locks: new name queued, moves + 1
W-->>P: 200 the order's view, or 409 registration_changed when registered after all
end
Note over W,D: next scan: commitment reused or committed again
Notes:
- Try again is sent with the registration id alone. It is refused for an order whose links were refused, one with 5 sends of a kind, and a code order whose code no longer pays. The reveal is kept while the sponsor nonce is unchanged and the commitment has
reveal_margin_seconds(default 900) left within the intent's deadline (Web/Names/Registration.hs:116-140,Names/Worker.hs:411-501,Config.hs:654). At the next scan a commitment with that margin left is reused; otherwise a new commit is sent, a second past the old commitment's lapse when one is on chain (Names/Worker.hs:175-206). - A move is accepted for a failed order, or for one whose links were refused, up to
max_order_moves(default 3). For a failed order the service checks first whether its name was registered after all, then refuses a move after 5 sends of a kind (Web/Names/Owner.hs:113-126,Config.hs:655). - Both names' locks are taken in hash order, and the first order's hash is kept. A paid order moved to a cheaper name is credited the difference; a code order is moved at price 0, its code reserved again (
Names/Turns.hs:27-32,Web/Names/Owner.hs:128-135,Names/Orders.hs:340-356,Names/Store.hs:787-813).
3.7 An owner's orders found
An owner without an order's link finds their orders by signing with their wallet; the ids found are used for Try again, a move, a spend or a refund.
sequenceDiagram
participant P as Names page
participant W as Web API
participant D as PostgreSQL
P->>P: owner signs "simplex.domains find OWNER TIMESTAMP" (EIP-191)
P->>W: POST /api/registration/find: owner, timestamp, signature
W->>D: the 50 newest orders, and older ones with a balance
W-->>P: 200: registrations with ids, phase, labelHash, sealed, heldBy
Notes:
- The signature and a timestamp within 600 s are checked; an owner without orders is answered
404. 5 finds a minute are allowed per client (Web/Names.hs:38,Web/Names/Owner.hs:44-67,Names/Signatures.hs:98-99,Names/Store.hs:815-837).
3.8 A balance spent on another name
Another name of the same owner is paid from an order's balance, wholly or with an invoice for the difference.
sequenceDiagram
participant P as Names page
participant W as Web API
participant D as PostgreSQL
participant E as Ethereum node
participant V as BTCPay or Stripe
participant L as Poller
P->>W: GET /api/registration/SOURCE, answered with its balance
P->>W: POST /api/registration/SOURCE/spend: signed order
W->>D: source order read
W->>W: its owner's signature checked, name and balance locks taken
W->>E: terms of the name's kind
W->>D: balance equal to the amount read and not held
W->>E: name status, rentPriceUSD equal to the price
alt balance covers the price, no method sent
W->>D: one transaction: registration queued, balance lowered by the price
W-->>P: 200: registrationId
else a difference to pay, method sent
W->>V: invoice for the price minus the balance
W->>D: one transaction: invoice open, registration unpaid, balance held
W-->>P: 200: invoice view of the new order, with fromBalance
alt paid
L->>D: settlement: registration queued, held balance spent
else unpaid past the expiry
L->>D: invoice expired, order closed, hold released
end
end
Notes:
methodis present exactly when the price is above the balance, and a card difference under 50 cents is refused (Web/Names/Orders.hs:280-306).- The spend is signed
simplex.domains spend SOURCE ...by the source order's owner, who owns the new order (Web/Names/Orders.hs:249-257,Names/Signatures.hs:104-106). - A balance amount other than the one read, or a hold, is answered
409 balance_changed. A hold by an overdue order is treated as none, and that order is closed in the spend's transaction (Names/Balances.hs:79-87,Names/Orders.hs:236-243). - The whole balance read is held by the difference order. At settlement the hold is spent; when it cannot be spent, the order is kept
queuedand an error is logged (Names/Store.hs:514-532,Orders.hs:200-204,Orders.hs:232-236). - Balances are credited when a paid order is set
taken(its whole price), when a paid order moves to a cheaper name (the difference), and with late or extra money (Names/Worker.hs:359-368,Names/Orders.hs:341-349,Names/LateCredits.hs:66-72).
3.9 Late crypto credited
Crypto paid to an invoice whose order has closed is credited to that order's balance.
sequenceDiagram
participant B as Buyer
participant V as BTCPay
participant W as Web API
participant L as Poller
participant D as PostgreSQL
B->>V: crypto to an invoice whose order closed
V->>W: POST /webhooks/btcpay, signature verified
W->>L: read hint
L->>V: read invoice: status Expired or Invalid
L->>D: payment recorded, the order stays closed
L->>V: current rate of the coin
L->>D: late credit row, balance credited at the lower rate
Notes:
- An invoice paid more crypto than it asked is settled as in 3.1, and only its confirmed units above the invoiced units are credited to the order's balance, the same way (
Providers/BTCPay.hs:448-452,Names/LateCredits.hs:74-104). InvoiceReceivedPaymentandInvoicePaymentSettledare among the BTCPay events acted on. From a BTCPay invoice readExpiredorInvalida closed signal is made, and at settlement the payment is recorded while the order is kept unpaid (Providers/BTCPay.hs:115,Providers/BTCPay.hs:448-454,Orders.hs:55-60,Orders.hs:180-198).- Only confirmed money is credited: crypto as its share of the invoice's amount, at the lower of the invoice's and the current rate, rounded down to the cent. With a current rate below half the invoice's, the money is never credited and is marked for support (
Names/LateCredits.hs:31-72,Names/LateCredits.hs:114-129). - Confirmed money not yet credited is credited again by a pass at the idle cadence (
Poller.hs:347-367). With late card money the invoice is set paid and the order kept closed; its cents are credited as they are (Orders.hs:184-189,Names/LateCredits.hs:91-95). Crypto sent to an invoice already recorded paid is left unrecorded, and an error naming it is logged at most hourly (Poller.hs:234-244).
3.10 A balance refunded by support
Support records the refund of a balance in the console and pays it back by hand.
sequenceDiagram
participant B as Buyer
participant O as Support
participant C as Console in run-cli mode
participant D as PostgreSQL
B--)O: asks for a refund with the order's reference (outside the service)
Note over O,C: the service is stopped, then run with --run-cli
O->>C: //refund REFERENCE
C->>D: order, balance, hold, the orders its money came through
C-->>O: balance, credited, refunded, paid by, the command to record it
O->>C: //refund REFERENCE CENTS
C->>D: under the balance's lock: amount 0, refunded raised by the cents
C-->>O: Recorded a refund ... Refund it now, by: ORDERS.
O--)B: money paid back by hand (outside the service)
Notes:
- The refund must equal the whole balance, and a held balance is refused, overdue or not.
//refundcloses no holder: its answer asks support to start the service, whose poller closes an overdue holder 10 minutes after its expiry, then to run the command again (Names/Balances.hs:40-65,Names/Store.hs:1046-1056,Service.hs:530-538). - The provider interface offers create, read, cancel, list, rate and webhook verification, so the money is paid back by hand (
Providers.hs:120-130). The buyer's email to chat@simplex.chat is described in the README; the page code is in the submodule (README.md:1371-1411). - The console starts only while the service is stopped, as the database lock is held by one process (
Store/Migrate.hs:46-54).
A failed paid order has no balance until it is closed. Support closes it with //close, which checks the chain first and records the refund in the same transaction that ends the order.
sequenceDiagram
participant B as Buyer
participant O as Support
participant C as Console in run-cli mode
participant N as Ethereum node
participant D as PostgreSQL
B--)O: asks for a refund of a failed order with its reference (outside the service)
Note over O,C: the service is stopped, then run with --run-cli
O->>C: //close REFERENCE
C->>D: the order, under its name's lock
C->>N: a mined register of the order, or the owner holding the name at the confirmation depth
alt the register went through
C->>D: order set registered
C-->>O: Nothing refunded: the register of order ID went through
else not registered
C->>D: under the balance's lock, one transaction: order set taken, price credited, the whole balance recorded as refunded
C-->>O: Closed order ID, failed at TIME ... Check at the provider ...; if not, refund it now, by: ORDERS.
O--)B: money paid back by hand, unless refunded before (outside the service)
end
- Only a failed order paid by invoice or balance is closed, and a lapsed committed order reads failed. A balance an order holds refuses the close and writes nothing (
Names/Worker.hs:515-564,Names/Worker.hs:376-380,Names/Orders.hs:366-373). - The answer names the failure time, as failed orders were refunded at the provider by hand before
//closeexisted (Service.hs:501-528,README.md:1436-1479).
3.11 A registered name's links edited
The owner's signed link changes are relayed to the resolver as one transaction, its gas paid by the registrar key.
sequenceDiagram
participant P as Names page
participant W as Web API
participant D as PostgreSQL
participant E as Ethereum node
participant S as Sender
participant R as Record edits lane
P->>P: owner signs SetText per changed link, or ClearRecords (EIP-712)
P->>W: POST /api/name/records: labelHash, 1 or 2 signed edits
W->>W: keys, links and signatures checked, one signer
W->>D: identical body found, else yearly limit checked
W->>E: latest block, owner and resolver, resolver nonce
W->>D: under the name's lock: limits again, edit inserted
W->>S: setTextWithSig, clearRecordsWithSig or multicall, to the resolver
S->>E: dry run, nonce, fees, signed, saved, broadcast
S->>D: receipt at the depth: transaction mined or reverted
R->>D: every 4 s, pending edits settled from their transactions
R-->>W: the waiting request is signalled
W-->>P: 200 tx, 409 record_reverted, or 504 edit_pending after 90 s
Notes:
SetTextandClearRecordsare signed in the EIP-712 domainSimplexResolver; the signer must be the registry's owner of a name on the default resolver, and the first nonce the owner's current resolver nonce, which the search answers asrecordsNonce(Names/Registration.hs:83-84,Names/Records.hs:185-195,Web/Names/Search.hs:105).- Edits relayed per name are bounded by
record_edits_per_year(default 3, from 1 to 100) in any 365 days, and every stored edit is counted, a reverted one too; at most 10 are relayed per name an hour, and 10 requests are accepted a minute per client (Names/Records.hs:116-152,Config.hs:286-289,Web/Http.hs:149). - The earliest deadline must be more than 600 s past the latest block's time (
Names/Records.hs:130-133,Names/Records.hs:185-195). - Two changes are sent in one
multicall, and both or neither are applied (Names/Registration.hs:205-207,Names/Records.hs:388-397). - An edit whose transactions were all dropped is judged from receipts, the owner's resolver nonce and the records, then resent before its deadline or settled (
Names/Records.hs:288-347). The records are read from the chain at the next search (Names/Contracts.hs:165-177).
3.12 Service start
The production container starts one process, which checks its configuration, the database lock and the node, starts the chat core, then starts all lanes.
sequenceDiagram
participant O as Operator
participant U as Startup
participant D as PostgreSQL
participant E as Ethereum node
participant C as Chat core
participant V as BTCPay
O->>U: docker compose up -d --build
U->>U: store_service.ini parsed in full
U->>D: pg_try_advisory_lock, held for the run
U->>E: eth_chainId equal to [chain] chain_id
U->>C: start: chat migrations, store migrations in preStartHook
C->>C: postStartHook: service requests on, bot address shown or created
C->>U: callback with the controller
U->>D: badge catalog seeded
U->>V: store payment methods read and logged
U->>D: sender loads saved transactions without an outcome
U->>E: name policy, community names and terms links read and logged
U->>U: sites exported, managed group found or created
U->>U: all lanes run together: requests, group, web, poller, names
Notes:
- The container runs
simplex-store-service -d BADGE_DB_CONN --create-schema --yes-migrate --service-config /etc/simplex-store-service/store_service.ini(compose.yml:14-20). - The process exits on a config error, a held lock, a chain id mismatch, an issuer key mismatch, a failed migration or a missing site build; compose restarts it on failure up to 5 times (
Main.hs:22-28,Service.hs:280-285,compose.yml:10). A node that does not answereth_chainIdis only warned of, unlessdev_keysare set (Service.hs:169-181). - The lanes are started in the chat core's callback, after
postStartHook, so after the bot address exists, unless--no-addressis passed (Chat/Core.hs:97-106,Service.hs:301-313,Service.hs:636-645). - The names lanes are the sender, the record edits lane, the names worker and the code sweep; all lanes are started together with
raceAny_from simplexmq (Service.hs:366-370). - Under
--run-clithe binary runs the terminal chat and the badge request lanes only (Service.hs:381-404).