@elgora/cli 10.2.0 → 12.0.0

package/README.md

@@ -33,16 +33,22 @@ answer.
   funds the new bounty. It reuses the saved approval for those bytes without
   another AI review, or reviews them first.
 - `poster:open-winning-submission` retrieves the finalized winning Submission
-  for the funding Poster and decrypts it locally.
+  for the funding Poster, decrypts it locally, and saves it as one `.tar.gz`.
 - `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.
-- `solver:submit` encrypts a Submission for the bounty's pinned Guardian roster
-  and prepares or sends the exact ElgoraHub transaction.
+- `solver:check <bounty_id> <folder_or_file>` runs the Submission check that
+  `solver:submit` and `guardian:open` also run, without submitting, and exits
+  1 on any issue.
+- `solver:submit <bounty_id> <folder_or_file>` packs a folder (subfolders
+  included) or a single file into one `.tar.gz`, encrypts it for the bounty's
+  pinned Guardian roster, and prepares or sends the exact ElgoraHub
+  transaction.
 - `guardian:judgeable` lists open bounties ready for Guardian review.
 - `guardian:open` signs the protected content read, then verifies and decrypts
-  one exact Solver and Submission pair.
+  one exact Solver and Submission pair, extracts its tree into a new or empty
+  folder, and reports the Submission check's issues.
 - `guardian:verdict` publishes a written Verdict and records the same Verdict
   on ElgoraHub.
 - `guardian:deliver-key` wraps one Solver–Submission content key for delivery
@@ -55,35 +61,92 @@ 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.
+
+### Which version a bounty needs
+
+It follows the profile the bounty's challenge declares:
+
+- `elgora_markdown_bounty_challenge_v1`: the latest release, at least 12.0.0.
+- `elgora_markdown_bounty_challenge_v0`: CLI 11, which CLI 12 names when it
+  refuses such a bounty; `npx` runs it beside the installed release:
+
+```sh
+npx @elgora/cli@11 poster:open-winning-submission <bounty_id>
+```
 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
+
+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>` |
 
-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.
+`--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
 can still use the roster and key it pinned.
 
-Never put private keys, decrypted artifacts, or raw Submission keys in command
+Never put private keys, decrypted files, or raw Submission keys in command
 arguments, logs, or submitted files. Each command reads only the secrets it
 needs.
 
@@ -107,15 +170,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 +200,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: