store: document the gas key

This commit is contained in:
sh-agents committed 2026-11-01 15:27:04 +00:00
1 parent 06adad1f18
commit dc6fb2649d
1 file changed
+267 -4
+267 -4
View File
@@ -101,7 +101,7 @@ section (omitting it disables card payments), an optional `[group]` section (omi
turns off the group's commands, though a group created earlier still has its code messages updated),
the poll cadence, optional `[apple]` and `[google]` sections that verify store purchases (see
[Store purchases](#store-purchases-app-store-and-google-play)), and optional `[names]` and `[chain]` sections for the names store (omitting both
turns it off).
turns it off), whose `[chain] service_key` is [the gas key](#the-gas-key).
`store_service.ini.example` is the committed template; `store_service.ini` itself is
gitignored, since a real one holds API keys and webhook secrets.
@@ -606,15 +606,278 @@ who hold them before anyone can pay. It is `off` by default. While it is on:
shell is unchanged;
- `POST /api/invoice` for a name answers `403 {"error": "codes_only"}`, before it reads the order,
so no order takes money for a name;
- search, link previews, code checks, code orders (`POST /api/name/register`) and the registration
view work as before. Webhooks and the poller still settle the invoices already open, and badges
sell as before.
- 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.
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)).
### 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
guardian sets. It holds no names.
The commands run from `scripts/store-service/` on the service host, with Foundry's `cast`
([getfoundry.sh](https://getfoundry.sh), checked with 1.5.1) and `jq`. They read the ini through this
shell function, which takes a `[chain]` key's value without surrounding spaces, tabs or a CR:
```
ini() { sudo sed -n "/^\[chain\]/,/^\[/s/^$1[[:space:]]*=[[:space:]]*\([^[:space:]]*\).*/\1/p" "${2:-config/store_service.ini}"; }
```
Keys and the RPC URL are read through `ini`, so they stay out of the shell history. A key is in
cast's arguments, and the RPC URL in curl's, visible to `ps` while it runs.
The ini is never edited in place. `sudoedit` refuses a file in a directory the invoking user can
write (sudo(8), sudoers(5) `sudoedit_checkdir`), as `scripts/store-service/config/` of the checkout is.
`sudo <editor>` would leave swap or backup files holding the key beside it, which git does not
ignore. So each change is made in a copy in a root-only directory and copied over the ini, which
keeps its owner and mode. `next/store_service.ini` and
the other copies below are ignored by git, as every `store_service.ini` is, and are outside the
image.
#### Create the key
Fill `[names]` and `[chain]` in a copy, with a `service_key = 0x...` line under `[chain]`. Then
generate the key into that line, so it is never printed, and put the copy in place:
```
sudo install -d -m 700 next && sudo cp -p config/store_service.ini next/store_service.ini
sudoedit next/store_service.ini
cast wallet new --json | jq -r '"s/^service_key[[:space:]]*=.*/service_key = " + .[0].private_key + "/"' | sudo sed -i -f - next/store_service.ini
cast wallet address "$(ini service_key next/store_service.ini)"
sudo cp next/store_service.ini config/store_service.ini && sudo rm -r next
```
The address check prints the key's address, as in `0xB2590B3a4fa5bEdda803F5f1F605803438C3F71E`, and
fails when the line was not replaced. The key is `0x` and 64 hex digits.
The ini holds the only copy of the key. It is gitignored, every `*.ini` is kept out of the image,
and compose mounts its folder read-only. Keep it owned by the service user with mode 600. The
service never logs the key; keep it out of logs and tickets too.
If a key was ever shown on a terminal, clear the screen and its scrollback (`clear && printf
'\e[3J'`, and `tmux clear-history` in tmux), and never show one in a recorded session.
#### Set up the shell
```
export ETH_RPC_URL="$(ini rpc_url)"
CONTROLLER=$(ini controller)
SPONSOR=$(ini sponsor)
REGISTRAR=$(cast wallet address "$(ini service_key)")
```
cast reads the node from `ETH_RPC_URL`, so no command below names it. The address check reads the
ini on disk, not the running service, which logs no address. To confirm the service runs with the
key, check that `cast nonce $REGISTRAR --block pending` rises after its next transaction.
#### Grant the allowance
Only the guardian, the controller's beneficiary, can set the allowance:
```
cast call $CONTROLLER 'beneficiary()(address)'
```
The guardian sends this call to `$SPONSOR`, with no value, from whatever wallet holds its key. Its
calldata, here for $1,000:
```
cast calldata 'setRegistrarAllowance(address,uint256)' $REGISTRAR $(cast parse-units 1000)
```
```
0x7f8ac8b8000000000000000000000000b2590b3a4fa5bedda803f5f1f605803438c3f71e00000000000000000000000000000000000000000000003635c9adc5dea00000
```
- From a key, with cast (`--interactive` prompts for the key; `--ledger` signs on a Ledger instead):
```
cast send $SPONSOR 'setRegistrarAllowance(address,uint256)' $REGISTRAR $(cast parse-units 1000) --interactive
```
- From a multisig such as Safe: submit that calldata to the sponsor address as a transaction with
value 0 in the Safe app.
Then anyone can check the result:
```
cast call $SPONSOR 'registrarAllowance(address)(uint256)' $REGISTRAR
```
```
1000000000000000000000 [1e21]
```
- The amount is in attoUSD: dollars × 10^18, or cents × 10^16. `cast parse-units 1000` gives $1,000.
- It replaces the allowance and does not add to it. To top it up, read what is left and send the
new total.
- Zero is the kill switch: `setRegistrarAllowance($REGISTRAR, 0)` stops every register from that
key in one transaction. A sender that is not the guardian is refused with `NotBeneficiary`.
- Each register spends the name's list price (`rentPriceUSD`, base plus premium) for its whole
duration, the free days before `[names] term_start` included. For example, 2 years of a name of 8
letters or more:
```
cast call $CONTROLLER 'rentPriceUSD(string,uint256)((uint256,uint256))' examplename 63072000
```
```
(100000000000000000000 [1e20], 0)
```
#### Fund the key
Send ETH on the chain of `[chain] chain_id` from any wallet, and top it up the same way. With cast:
```
cast send $REGISTRAR --value 1ether --interactive
```
The gas below was measured on a local anvil deployment of the contracts (the names webapp's
`dev/deploy.ts`), with a 63-letter label and links of 4096 bytes, the most the service accepts:
| Transaction | Gas limit | Gas used | Limit × 100 gwei |
|---|---|---|---|
| `commit` | 58,983 | 53,521 | 0.0059 ETH |
| `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 |
- 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`.
- `gas_limit_cap` (default 8,000,000) must stay above 6,791,417: a transaction whose estimate is
above it is not sent.
#### Check the balance and transactions in flight
```
cast balance $REGISTRAR --ether
cast nonce $REGISTRAR --block latest
cast nonce $REGISTRAR --block pending
```
The balance prints as `1.000000000000000000`. The `latest` nonce counts the key's mined
transactions, and the `pending` one adds those waiting in the node's pool; the difference is what is
in flight. The same reads through JSON-RPC answer in hex wei and hex counts
(`{"jsonrpc":"2.0","id":1,"result":"0xde0b6b3a7640000"}`, which `cast to-unit 0xde0b6b3a7640000 ether`
prints as `1`):
```
curl -s -X POST -H 'content-type: application/json' --data '{"jsonrpc":"2.0","id":1,"method":"eth_getBalance","params":["'"$REGISTRAR"'","latest"]}' "$ETH_RPC_URL"
curl -s -X POST -H 'content-type: application/json' --data '{"jsonrpc":"2.0","id":1,"method":"eth_getTransactionCount","params":["'"$REGISTRAR"'","latest"]}' "$ETH_RPC_URL"
curl -s -X POST -H 'content-type: application/json' --data '{"jsonrpc":"2.0","id":1,"method":"eth_getTransactionCount","params":["'"$REGISTRAR"'","pending"]}' "$ETH_RPC_URL"
```
A transaction the node refused is in neither count. The service's own list is the `pending` rows of
its transactions table, here with compose's default database and schema:
```
psql "postgresql://simplex@127.0.0.1:5432/badge_service" -c "SELECT registrar_nonce, kind, sent_at FROM simplex_v1_chat_schema.sx_badge_service_name_transactions WHERE status = 'pending' ORDER BY registrar_nonce"
```
#### When funds or the allowance run out
`docker compose logs store-service` shows:
- `[ERROR …] names sender: nonce <n>: not sent: …`, with the node's `insufficient funds` message,
when the key cannot pay. The transaction is saved and sent again every few seconds, so funding the
key is enough and needs no restart. The line is logged again only when the node's message changes.
- `[ERROR …] names worker: registration <id> failed: the registrar's allowance on the sponsor is
used up; the guardian raises it with setRegistrarAllowance` when the sponsor refuses a register
with `InsufficientAllowance`. The order is failed; a code order keeps its code for Try again.
- `[WARN …] names sender: the latest block needs <wei> wei per gas, above max_fee_per_gas <cap>;
the transaction waits` when fees are above the cap. Nothing is signed until they fall.
- `[WARN …] names sender: nonce <n>: not replaced: a replacement would pay over max_fee_per_gas
<cap>` when a transaction stuck in the pool cannot be bumped within the cap.
#### Rotate the key
The service resumes its saved transactions at start and gives new ones nonces after theirs. Those
are signed by the key that sent them, so started on another key it would give that key's
transactions nonces it has not reached, and they would never be mined. Rotate only with no `pending`
row, at a quiet time: every stop takes the store offline, and each order sends its register about a
minute after its commit.
1. Keep a copy of the old ini, create the new key in another, fund it, and have the guardian grant
it an allowance, as above for `$NEW`:
```
sudo install -d -m 700 prev next
sudo cp -p config/store_service.ini prev/store_service.ini && sudo cp -p config/store_service.ini next/store_service.ini
cast wallet new --json | jq -r '"s/^service_key[[:space:]]*=.*/service_key = " + .[0].private_key + "/"' | sudo sed -i -f - next/store_service.ini
OLD=$(cast wallet address "$(ini service_key prev/store_service.ini)")
NEW=$(cast wallet address "$(ini service_key next/store_service.ini)")
```
2. Stop the service and count the `pending` rows:
```
docker compose stop store-service
psql "postgresql://simplex@127.0.0.1:5432/badge_service" -tAc "SELECT count(*) FROM simplex_v1_chat_schema.sx_badge_service_name_transactions WHERE status = 'pending'"
```
On `0`, go to step 3. Otherwise `docker compose start store-service` on the old key, let them
settle (`confirmations` blocks after they are mined), wait for a pause in the orders, and repeat
this step. For a drain that new orders cannot hold up, start the old key with
`max_fee_per_gas = 1` under `[chain]` instead:
```
sudo install -d -m 700 drain && sudo cp -p config/store_service.ini drain/store_service.ini
sudoedit drain/store_service.ini
sudo cp drain/store_service.ini config/store_service.ini
docker compose start store-service
```
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
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.
3. Put the new ini in place, start, and check that the ini on disk now holds the new key:
```
sudo cp next/store_service.ini config/store_service.ini
docker compose start store-service
cast wallet address "$(ini service_key)"
```
It prints `$NEW`. After the next order's commit, `cast nonce $NEW --block pending` is above 0,
and `cast nonce $OLD --block pending` stays where it was.
4. The guardian zeroes the old key's allowance, sending this calldata as in
[Grant the allowance](#grant-the-allowance), then anyone checks it reads 0:
```
cast calldata 'setRegistrarAllowance(address,uint256)' $OLD 0
cast call $SPONSOR 'registrarAllowance(address)(uint256)' $OLD
```
5. Send the old key's ETH back to a plain account (a transfer to a contract such as a Safe needs
more than the 21,000 gas used here), then delete the copies. The first send leaves 0.01 ETH for
the fees. The second sweeps the rest, as a legacy transaction that pays exactly its gas price,
twice the node's current one, so the balance ends at 0:
```
cast balance $OLD --ether
cast send <account> --value <balance - 0.01>ether --private-key "$(ini service_key prev/store_service.ini)"
P=$(( 2 * $(cast gas-price) ))
cast send <account> --legacy --gas-limit 21000 --gas-price $P --value $(( $(cast balance $OLD) - 21000 * P )) --private-key "$(ini service_key prev/store_service.ini)"
cast balance $OLD
sudo rm -rf prev next drain
```
The last balance prints `0`. A negative value, from fees above about 150 gwei, makes cast refuse
the sweep; run it again when they fall.
## Issuing codes
Operators issue codes two ways: from the service's own command line in `--run-cli` mode, and from the