@elgora/cli 10.1.0 → 11.0.0

package/README.md

@@ -34,7 +34,7 @@ answer.
   another AI review, or reviews them first.
 - `poster:open-winning-submission` retrieves the finalized winning Submission
   for the funding Poster and decrypts it locally.
-- `check-page <bounty_challenge_md_path|->` checks structural conformance offline,
+- `check-challenge <bounty_challenge_md_path|->` checks structural conformance offline,
   returns an issue list and exits non-zero on failure. It needs no wallet or
   network and does not replace hosted semantic readiness review.
 - `spec-commitment` reproduces the challenge's `spec_commitment` offline.
@@ -55,29 +55,74 @@ answer.
   creates the small advisory `VerificationRecord` for a finalized bounty, which
   `GET /api/bounties/<bounty_id>` inlines.
 
-Run `elgora-cli help <command>` for exact arguments and environment variables.
+Run `elgora-cli help <command>` for exact arguments, options, and secrets.
 Run `elgora-cli --version` to print the installed release's version; it is the
 version of the npm package or standalone binary in use, stamped in at build
 time, so it stays correct however the CLI was installed.
 
-## Wallets and keys
+## Signers
 
-Posters use `ELGORA_POSTER_PRIVATE_KEY`. Solvers should normally use
-`--solver-address` and sign the emitted EIP-712 requests and prepared
-transaction with an external wallet; `ELGORA_SOLVER_PRIVATE_KEY` is an optional
-local testing convenience. Each emitted `typed_data` is in the
-`eth_signTypedData_v4` shape, with `EIP712Domain` in its types; for ethers v6,
-delete `types.EIP712Domain` before passing it to `signTypedData`. Claimants can
-use `--claimant-address`, or `ELGORA_CLAIMANT_PRIVATE_KEY` for a local test
-wallet.
+Functional choices are options; the environment holds only secrets. A command
+names any option it does not accept. `--signer` chooses how its one account
+signs:
+
+| `--signer` | Use | Settings |
+| --- | --- | --- |
+| `local` (default) | a private key | `ELGORA_PRIVATE_KEY` |
+| `privy` | a Privy server wallet, e.g. an unattended Guardian | `--privy-wallet-id <id>`, optional `--privy-sponsor`; `PRIVY_APP_ID`, `PRIVY_APP_SECRET`, optional `PRIVY_AUTHORIZATION_PRIVATE_KEY` |
+| `manual` | your own wallet tooling, so no key enters this process | `--signer-address <address>` |
+
+`--signer-address` also checks the account any signer resolves to. The account
+may be a plain key, a contract wallet (ERC-1271/6492), or an EIP-7702 account;
+Elgora verifies every signature on chain.
+
+### `--signer manual`
+
+For each signature or transaction the command needs, it writes a request file
+and prints one line on stdout:
+
+```json
+{"event":"signer.request_written","kind":"api_request_approval","request_path":"…/01-api_request_approval.request.json","response_path":"…/01-api_request_approval.response","expires_at":"…"}
+```
+
+The request holds `kind`, `address`, `chain_id`, and one of `typed_data`
+(EIP-712, `eth_signTypedData_v4` shape), `message` (hex bytes for
+`personal_sign`), or `calls` (`to`, `value`, `data`). Sign or send it with your
+own wallet, then write the signature, or the transaction hash(es) separated by
+spaces, to `response_path` before `expires_at` (25 minutes for a signature, 60
+for transactions). The CLI verifies each signature on chain and keeps
+checking an answer that does not pass, so one refused during an RPC outage
+still counts once the check succeeds. An unanswered transaction request ends in
+`verification_pending`, since it may have been sent anyway.
+
+### Transactions
+
+Commands send their transactions last. `--prepare-only` prints them as
+`<event>.calls_prepared` (`chain_id`, `from`, `calls`) instead. A sent
+transaction counts only once ElgoraHub shows its effect: the command prints
+`<event>.recorded`, fails, or prints `<event>.verification_pending` and exits
+75 when it may be on chain but is not confirmed yet. Check ElgoraHub before
+running it again; a second `poster:publish-fund` funds a second bounty.
+
+The CLI checks only real transactions: their receipts and ElgoraHub, through
+its RPC. It never talks to a bundler or paymaster and cannot resolve a user
+operation hash or a Safe transaction id. A smart wallet's calls count once the
+wallet hands back the hash of the transaction they were mined in; with
+`--signer manual`, write that hash, and with `--signer privy --privy-sponsor`,
+Privy reports it.
+
+A local key funds a bounty with one USDC authorization (EIP-3009); any other
+signer funds through `approve`, then `createBounty`.
+
+### Guardian keys
 
 Guardian commands use two different kinds of secret:
 
-- `ELGORA_GUARDIAN_ACCOUNT_PRIVATE_KEY` is the Guardian's Ethereum account key.
-  It signs protected Submission reads, API writes, and `commitVerdict`
-  transactions.
+- The Guardian's account, as above. It signs protected Submission reads, API
+  writes, the roster key proof, and `commitVerdict` transactions.
 - `ELGORA_GUARDIAN_PRIVATE_KEYS_JSON` contains retained X25519 encryption keys.
-  They decrypt Submissions and never sign transactions.
+  They decrypt Submissions and never sign. They stay local whatever
+  `--signer` is.
 
 A Guardian may retain old and new X25519 keys after rotating the public key for
 the same account. The CLI tries the retained keys locally so an earlier bounty
@@ -107,15 +152,16 @@ elgora-cli claim --network 84532 7                   # the same, by chain id
 export ELGORA_CHAIN_ID=84532                         # testnet for every run in this shell
 ```
 
-The chain's public RPC, the ElgoraHub address, the escrow token, and the subgraph
-endpoint are all defaulted from that chain id, so targeting Elgora's own
-deployment needs no other configuration. They stay individually settable:
-`ELGORA_HUB_ADDRESS`, `ELGORA_RPC_URL`, and `ELGORA_SUBGRAPH_ENDPOINT` override
-what the chain id resolved — a local anvil stack needs them, since its addresses
-change on every run. `elgora-cli help <command>` lists what that command reads
-and which values it defaults. Supply a complete, coherent configuration when
-targeting a deployment this CLI release does not know about, and do not mix
-addresses or endpoints from different deployments.
+The chain's public RPC, the ElgoraHub address, and the subgraph endpoint are all
+defaulted from that chain id, so targeting Elgora's own deployment needs no
+other configuration. They stay individually settable: `--hub-address`,
+`--rpc-url`, and `--subgraph-endpoint` (or `ELGORA_HUB_ADDRESS`,
+`ELGORA_RPC_URL`, `ELGORA_SUBGRAPH_ENDPOINT`) override what the chain id
+resolved — a local anvil stack needs them, since its addresses change on every
+run. The escrow token is read from ElgoraHub. `elgora-cli help <command>` lists
+the options that command accepts. Supply a complete, coherent configuration
+when targeting a deployment this CLI release does not know about, and do not
+mix addresses or endpoints from different deployments.
 
 The API follows the chain too: `https://elgora.ai` for `base` and
 `https://testnet.elgora.ai` for `base-sepolia`. Commands that use the public API
@@ -136,18 +182,6 @@ wallet, gets the same result a bounty page visit would — it reads that page's
 own `GET /api/bounties/<bounty_id>`. A bounty with no record yet fails with the
 reason the API gave.
 
-## Solver custody
-
-`solver:submit --solver-address <address> <bounty_id> <artifact_dir>` prints an
-approval request whenever the API needs a signed write. Sign its exact
-`typed_data` value and return only the hex signature on stdin. The CLI then
-checks the pinned Guardian roster directly against ElgoraHub, verifies the four
-prepared `submit` values, and locally encodes the transaction for the same
-wallet.
-
-Without `--solver-address`, `ELGORA_SOLVER_PRIVATE_KEY` signs and sends the same
-requests locally. It is intended only for controlled testing.
-
 ## Development
 
 From the repository root: