@continuumdao/ctm-mpc-defi 0.2.60 → 0.2.61

package/dist/agent/skills/railgun/SKILL.md

@@ -19,9 +19,14 @@ The 0zk address and its balances are stored on the KeyGen record. Each node hold
 | Public tokens that show the Railgun icon | `ctm_railgun_fetch_popular_assets` |
 | This KeyGen's shielded balances | `ctm_railgun_fetch_private_balances` |
 | Shield a public ERC-20 into the 0zk address | `ctm_railgun_build_shield_multisign` |
+| Quote the shield, transfer, or unshield fee | `ctm_railgun_fee_quote` |
 | Start a private transfer | `ctm_railgun_private_transfer` |
 | Start an unshield to a public address | `ctm_railgun_unshield` |
-| Agree this node's share of a pending spend | `ctm_railgun_agree_spend` |
+| Agree or reject a pending spend from Join, node chat, or Telegram | `list_sign_requests_awaiting_join`, then `sign_request_agree` |
+| Execute a private transfer after the other nodes have accepted | `list_sign_requests_ready`, then `broadcast_sign_result` with the `RailgunSpend:` id. No Get Sig |
+| Agree this node's share when the spend id is already known | `ctm_railgun_agree_spend` |
+
+Call `ctm_railgun_fee_quote` before a shield, private transfer, or unshield, and tell the user the fee. Shield and unshield take a Railgun percentage from the amount. A private transfer has no protocol fee. Unshield and private transfer also take a broadcaster fee from the private balance. `purpose` on a private transfer or unshield, and `purposeText` on a shield, is the Purpose shown on Join. `thoughts` on `sign_request_agree` or `ctm_railgun_agree_spend` is stored on the Railgun spend the same way as on a normal sign request.
 
 Call `ctm_railgun_ensure_wallet` first. Use the returned `railgunAddress` as the shield recipient. Call `ctm_railgun_fetch_private_balances` before an unshield or private transfer. Pass `refresh: true` when the stored scan may be stale. If `walletConfigured` is false, call `ctm_railgun_ensure_wallet` and then fetch again.
 
@@ -29,11 +34,15 @@ Call `ctm_railgun_ensure_wallet` first. Use the returned `railgunAddress` as the
 
 ## Shield
 
-1. Call `ctm_railgun_build_shield_multisign` without `shieldSignature`, with `railgunAddress` from `ctm_railgun_ensure_wallet`. Submit that personal_sign request (`sign_request_agree`, then `trigger_sign_result`).
-2. `broadcast_sign_result` on that request returns the shield-key signature in `txHashes[0]` and does not send a transaction. Call this tool again with `shieldSignature` set to that hex. Submit the resulting approve-and-shield transaction.
+`ctm_railgun_ensure_wallet` returns `shieldSignature` when this KeyGen already has one. Do not pass `shieldSignature` into `ctm_railgun_build_shield_multisign`. The server reads it from the KeyGen.
+
+1. Call `ctm_railgun_build_shield_multisign` with the amount and the 0zk address from `ctm_railgun_ensure_wallet`. If a shield key is stored, this submits the approve-and-shield transaction.
+2. If no shield key is stored, the call returns a personal_sign. Submit it with `sign_request_agree`, then `trigger_sign_result`. The signature is stored on the KeyGen. Call `ctm_railgun_build_shield_multisign` again with the same amount and 0zk address. Do not pass `shieldSignature`.
 
-The first call signs Railgun's shield message. The second call builds the EVM shield. If allowance is short, the second call includes an approve, and a zero-approve reset when a non-zero allowance is still too small. Shielding spends the KeyGen threshold key, not the 0zk spending key.
+The personal_sign is only of the text `RAILGUN_SHIELD`. It does not contain the amount. If allowance is short, the shield call includes an approve, and a zero-approve reset when a non-zero allowance is still too small. Shielding spends the KeyGen threshold key, not the 0zk spending key.
 
 ## Private transfer and unshield
 
-These start a pending spend and agree this node's share. The response is `pending` until `approvals` reaches `quorum`. Tell the user the `spendId` and ask an operator on each other KeyGen node to call `ctm_railgun_agree_spend` with that id. When the quorum is reached, the node that started the spend builds the proof and discards the spending key. A later balance scan shows the result. Unshield defaults the recipient to the KeyGen Ethereum address.
+A private transfer is signed with this node's management key before the spend is stored. An unshield is signed with this node's management key the same way. These start a pending spend and agree this node's share. The response is `pending` until `approvals` reaches `quorum`. The same spend appears on the other KeyGen nodes in `list_sign_requests_awaiting_join` with `agreementKind: railgun_spend`. When an operator asks whether any sign requests are pending, in node chat or Telegram, include those rows. Show the asset, `amountWei` in base units, the destination address, the memo, the proposal time, and the deadline. Agree or reject with `sign_request_agree` and the row's `requestId` (`RailgunSpend:<keyGenId>:<spendId>`). `accept: false` rejects it. Do not call `trigger_sign_result`. `ctm_railgun_agree_spend` is the same agree when the keyGen id and spend id are already known. When the quorum is reached, the spend leaves Join and appears on the originator's Execute tab, and in `list_sign_requests_ready` on that node. The originator executes it with `broadcast_sign_result` and that same requestId. That builds the proof and submits it to the Railgun broadcaster. There is no Get Sig step. Automated jobs must skip `agreementKind: railgun_spend`. A later balance scan shows the result. Unshield defaults the recipient to the KeyGen Ethereum address.
+
+A private transfer to a contact uses `toContactName` on `ctm_railgun_private_transfer`. That reads `railgunAddress` from the address book, not the contact’s Ethereum `address`. If the contact has no 0zk address, say so and do not invent one. Save one with `add_to_address_book_registry` on an Ethereum contact that is not a contract. Pass `railgunAddress` as an empty string to clear it. `remove_from_address_book_registry` removes the contact, including its 0zk address.