From cffc9f4a7364c33beb2d09157bd1b9ca139ee38a Mon Sep 17 00:00:00 2001 From: sh-agents <350651734+sh-agents@users.noreply.github.com> Date: Mon, 2 Nov 2026 06:58:36 +0000 Subject: [PATCH] store: document link edits --- apps/simplex-store-service/README.md | 52 +++++++++++++++++++++++----- 1 file changed, 43 insertions(+), 9 deletions(-) diff --git a/apps/simplex-store-service/README.md b/apps/simplex-store-service/README.md index c7dd8afb00..c7a8bc3b5c 100644 --- a/apps/simplex-store-service/README.md +++ b/apps/simplex-store-service/README.md @@ -660,10 +660,11 @@ restart, search each listed name on the names site and check that it shows as a Every order signs the terms the buyer agreed to: `terms_version`, followed by `/community` for a listed name. The service stores them with the order, so an open order keeps the terms it signed -after an edit. An order signed with any other value answers `409 terms_changed` with the current terms and +after an edit, and every move signs the current terms for the name it moves to, and stores them. An +order or a move signed with any other value answers `409 terms_changed` with the current terms and the name's community entry, and the page asks again. An exact resend is still answered after the version changed. -**Upgrading:** a page that sends no `terms` gets `bad_request` on every order and spend, so the +**Upgrading:** a page that sends no `terms` gets `bad_request` on every order, spend and move, so the page and the service are deployed together. ### Codes-only launch @@ -677,18 +678,42 @@ who hold them before anyone can pay. It is `off` by default. While it is on: - `POST /api/invoice` for a name and `POST /api/registration/:id/spend` answer `403 {"error": "codes_only"}`, before they read the order, so no order takes money for a name; - search, link previews, code checks, code orders (`POST /api/name/register`), the registration - view, the reveal and Try again work as before. Webhooks and the poller still settle the invoices already open, and badges sell as before. + view, `find`, the reveal, Try again, another name and record edits work as before. Webhooks and the + poller still settle the invoices already open, and badges sell as before. The setting is read at startup, and the export is written then, so switching it is an edit of the ini and a restart, with the same build. Codes for investors come from the group (needs `[group]`, see [From the group](#from-the-group)) or from `//issue name` in `--run-cli` (see [From the command line](#from-the-command-line)). +### Link edits + +Each "Edit links" save is one request, relayed by the service as one transaction whose gas it pays +(see [The gas key](#the-gas-key)): one changed link as `setTextWithSig` (or `clearRecordsWithSig`), +both links as the resolver's `multicall` of two `setTextWithSig` calls, which lands both or neither. +`[names] record_edits_per_year` (default 3, from 1 to 100, read at startup) bounds them per name in +any 365 days: + +- each accepted request counts once, from when it is stored to be sent, whether it changes one link + or both, or clears them; +- links set at registration ride on the register transaction and count nothing; +- a request refused before any transaction, a dry run that reverts, a send the chain fails, and an + edit that reverts on chain (or expires) count nothing, the last once it settles. A pending edit + counts until then; +- an exact resend of an accepted request is answered as before and counts nothing more. + +When a name has none left, `POST /api/name/records` answers +`429 {"error": "edit_limit", "nextAt": }` before any chain read, and the search answer +for the name carries `recordEdits: {"left": 0, "nextAt": …}`, from which the page shows when the +owner can edit again. Lowering the setting keeps the edits already counted. The hourly cap of 10 +relayed requests per name still applies, and still counts reverted ones. + ### The gas key `[chain] service_key` is the registrar key: an Ethereum account (EOA) that sends every names -transaction, `commit` to the controller and `registerWithCredit` to the sponsor. It pays only -their gas, in ETH. The names' rent is spent from its allowance on the sponsor, in USD, which the +transaction, `commit` to the controller, `registerWithCredit` to the sponsor, and the owners' record +edits (`setTextWithSig`, `clearRecordsWithSig`, or a `multicall` of two) to the resolver. It pays +only their gas, in ETH. The names' rent is spent from its allowance on the sponsor, in USD, which the guardian sets. It holds no names. The commands run from `scripts/store-service/` on the service host, with Foundry's `cast` @@ -817,14 +842,23 @@ The gas below was measured on a local anvil deployment of the contracts (the nam | `registerWithCredit`, no links | 568,116 | 504,408 | 0.0568 ETH | | `registerWithCredit`, one link | 3,673,412 | 3,489,551 | 0.3673 ETH | | `registerWithCredit`, two links | 6,791,417 | 6,467,815 | 0.6791 ETH | +| `setTextWithSig`, a new link | 3,026,449 | 3,026,449 | 0.3026 ETH | +| `setTextWithSig`, a link replacing one | 462,289 | 462,289 | 0.0462 ETH | +| `setTextWithSig`, a link removed | 698,644 | 558,916 | 0.0699 ETH | +| `clearRecordsWithSig` | 80,312 | 80,312 | 0.0080 ETH | +| `multicall`, two new links | 6,054,042 | 6,008,868 | 0.6054 ETH | - The service sets each transaction's gas limit to its estimate and its max fee to at most `max_fee_per_gas` (default 100 gwei). The node accepts a transaction only while the balance covers its limit × max fee, so the last column is what each one needs held. What it is charged is gas used × the block's base fee plus tip, usually far less. - An order is one commit and one register: 0.6850 ETH at the cap with two links, 0.0627 ETH with - none. The expected orders × 0.6850 ETH pays for all of them even at the cap. The figures scale - with `max_fee_per_gas`. + none. The expected orders × 0.6850 ETH, plus 0.6054 ETH per expected Save of both links (0.3026 ETH + for one), pays for all of them even at the cap. A name's link edits are at most + `record_edits_per_year` (3) a year, see [Link edits](#link-edits). The figures scale with + `max_fee_per_gas`. +- A Save of both links in one `multicall` uses 26,906 gas less than the same two edits sent as two + transactions with links of 4096 bytes, and 28,082 less with short links. - `gas_limit_cap` (default 8,000,000) must stay above 6,791,417: a transaction whose estimate is above it is not sent. @@ -909,7 +943,7 @@ minute after its commit. ``` With a cap of 1 wei the service signs no new transaction. Each new one waits and logs the fee - warning. The saved transactions are still + warning, and an owner's link edit is answered as unavailable. The saved transactions are still followed and settle. They are not bumped above the cap, so one that stays pending for long needs the old ini back (`sudo cp prev/store_service.ini config/store_service.ini` and a restart) to be replaced. Step 3 puts the full cap back, since `next/` was copied before. @@ -1077,7 +1111,7 @@ them later is logged as not applied and changes nothing. ## Refunding a name balance A paid name order keeps its money as a balance when it ends `taken` (another buyer registered the -name first), when a payment reaches its invoice +name first), when it moves to a cheaper name (the difference), when a payment reaches its invoice after the invoice closed, and when its invoice was paid more crypto than it asked (the extra). The buyer spends a balance on another name from Your names, or asks for it back: the page tells them to write to chat@simplex.chat with the order's reference, which is its invoice id, or its registration