From bce20b0297daf9a00c2139e066bf59701c237bf3 Mon Sep 17 00:00:00 2001 From: sh-agents <350651734+sh-agents@users.noreply.github.com> Date: Mon, 9 Nov 2026 13:39:08 +0000 Subject: [PATCH] store: describe //close in the names design --- apps/simplex-store-service/docs/names.md | 33 +++++++++++++++++++++--- 1 file changed, 30 insertions(+), 3 deletions(-) diff --git a/apps/simplex-store-service/docs/names.md b/apps/simplex-store-service/docs/names.md index c21b716ea0..34bf505fdb 100644 --- a/apps/simplex-store-service/docs/names.md +++ b/apps/simplex-store-service/docs/names.md @@ -83,7 +83,7 @@ How a request flows: 7. 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`](../src/StoreService/Names/Sender.hs#L107-L131), [`Names/Sender.hs:151-226`](../src/StoreService/Names/Sender.hs#L151-L226)). 8. 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`](../src/StoreService/Names/Records.hs#L156-L263), [`Names/Records.hs:265-302`](../src/StoreService/Names/Records.hs#L265-L302)). 9. Link profiles are read through the chat core's connect plan, and the link data through SMP servers ([`Names/Profiles.hs:269-274`](../src/StoreService/Names/Profiles.hs#L269-L274), [`Chat/Library/Internal.hs:1723-1726`](../../../src/Simplex/Chat/Library/Internal.hs#L1723-L1726)). -10. 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 and record refunds ([`Group.hs:263-300`](../src/StoreService/Group.hs#L263-L300), [`Main.hs:25-28`](../Main.hs#L25-L28), [`Service.hs:412-430`](../src/StoreService/Service.hs#L412-L430)). +10. 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`](../src/StoreService/Group.hs#L263-L300), [`Main.hs:25-28`](../Main.hs#L25-L28), [`Service.hs:414-433`](../src/StoreService/Service.hs#L414-L433)). 11. 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`](../src/StoreService/Store/Migrate.hs#L46-L58)). --- @@ -106,7 +106,7 @@ How a request flows: | 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`](../src/StoreService/Service.hs#L293-L313), [`Service.hs:636-645`](../src/StoreService/Service.hs#L636-L645), [`Names/Profiles.hs:269-274`](../src/StoreService/Names/Profiles.hs#L269-L274) | | Badge request lanes | Badge requests on the bot address, present before this PR: three lanes, each answer sent as `APISendServiceResponse`. | [`Service.hs:572-657`](../src/StoreService/Service.hs#L572-L657) | | 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`](../src/StoreService/Group.hs#L87-L304), [`Group/Command.hs:59-73`](../src/StoreService/Group/Command.hs#L59-L73), [`Group/Command.hs:216-220`](../src/StoreService/Group/Command.hs#L216-L220) | -| 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` and `//refund`. | [`Main.hs:25-28`](../Main.hs#L25-L28), [`Service.hs:381-506`](../src/StoreService/Service.hs#L381-L506) | +| 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`](../Main.hs#L25-L28), [`Service.hs:382-538`](../src/StoreService/Service.hs#L382-L538) | | 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`](../src/StoreService/Store/Postgres/Migrations.hs#L276-L473), [`compose.yml:16`](../../../scripts/store-service/compose.yml#L16) | | 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`](../../../.gitmodules#L4-L7), [`Web/Names.hs:28-44`](../src/StoreService/Web/Names.hs#L28-L44) | | 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`](../src/StoreService/Providers/BTCPay.hs#L267-L367), [`Providers/BTCPay.hs:524-538`](../src/StoreService/Providers/BTCPay.hs#L524-L538), [`Providers/BTCPay.hs:555-578`](../src/StoreService/Providers/BTCPay.hs#L555-L578) | @@ -513,10 +513,37 @@ sequenceDiagram Notes: -- The refund must equal the whole balance, and a held balance is refused, overdue or not. `//refund` closes no holder: its answer asks support to start the service, whose poller closes an overdue holder 10 minutes after its expiry, then to run `//refund` again ([`Names/Balances.hs:40-65`](../src/StoreService/Names/Balances.hs#L40-L65), [`Names/Store.hs:1046-1056`](../src/StoreService/Names/Store.hs#L1046-L1056), [`Service.hs:498-506`](../src/StoreService/Service.hs#L498-L506)). +- The refund must equal the whole balance, and a held balance is refused, overdue or not. `//refund` closes 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`](../src/StoreService/Names/Balances.hs#L40-L65), [`Names/Store.hs:1046-1056`](../src/StoreService/Names/Store.hs#L1046-L1056), [`Service.hs:530-538`](../src/StoreService/Service.hs#L530-L538)). - The provider interface offers create, read, cancel, list, rate and webhook verification, so the money is paid back by hand ([`Providers.hs:120-130`](../src/StoreService/Providers.hs#L120-L130)). The buyer's email to chat@simplex.chat is described in the README; the page code is in the submodule ([`README.md:1371-1411`](../README.md#L1371-L1411)). - The console starts only while the service is stopped, as the database lock is held by one process ([`Store/Migrate.hs:46-54`](../src/StoreService/Store/Migrate.hs#L46-L54)). +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. + +```mermaid +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`](../src/StoreService/Names/Worker.hs#L515-L564), [`Names/Worker.hs:376-380`](../src/StoreService/Names/Worker.hs#L376-L380), [`Names/Orders.hs:366-373`](../src/StoreService/Names/Orders.hs#L366-L373)). +- The answer names the failure time, as failed orders were refunded at the provider by hand before `//close` existed ([`Service.hs:501-528`](../src/StoreService/Service.hs#L501-L528), [`README.md:1436-1479`](../README.md#L1436-L1479)). + --- ### 3.11 A registered name's links edited