@elgora/cli 7.1.2

package/README.md

@@ -0,0 +1,138 @@
+# elgora-cli
+
+`elgora-cli` lets Posters, Solvers, Guardians, and claimants perform their part
+of an Elgora bounty from their own machine. It is a thin client: ElgoraHub owns
+the bounty lifecycle, current Verdicts, settlement, claims, and refunds.
+
+The CLI does not tally Guardian Verdicts or settle bounties. Every selected
+Guardian must record a Verdict; ElgoraHub decides when two-thirds of the
+pinned roster match.
+
+## Install
+
+```sh
+npm install -g @elgora/cli
+elgora-cli --help
+```
+
+Or run one command without installing:
+
+```sh
+npx @elgora/cli --help
+```
+
+## Commands
+
+- `poster:publish-fund` publishes approved `bounty_challenge.md` bytes and
+  funds the new bounty.
+- `poster:open-winning-submission` retrieves the finalized winning Submission
+  for the funding Poster and decrypts it locally.
+- `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.
+- `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.
+- `guardian:verdict` publishes a written Verdict and records the same Verdict
+  on ElgoraHub.
+- `guardian:deliver-key` repairs delivery for one exact Solver and Submission
+  pair when ElgoraHub still permits it.
+- `claim` prepares or sends the winning Solver's reserved award or the
+  Poster's queued refund, as selected from finalized ElgoraHub state.
+- `verification-record` is a plain, unauthenticated GET that fetches or lazily
+  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.
+
+## Wallets and keys
+
+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. Claimants can use `--claimant-address`, or
+`ELGORA_CLAIMANT_PRIVATE_KEY` for a local test wallet.
+
+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.
+- `ELGORA_GUARDIAN_PRIVATE_KEYS_JSON` contains retained X25519 encryption keys.
+  They decrypt Submissions and never sign transactions.
+
+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
+arguments, logs, or submitted files. Each command reads only the secrets it
+needs.
+
+## Deployment configuration
+
+Every command accepts `--network <name|chain id>`, which selects the deployment
+for that invocation without touching the environment. It takes a network name
+(`base`, `base-sepolia`, `local`) or that network's chain id (`8453`, `84532`,
+`31337`), and sets `ELGORA_CHAIN_ID` — the variable the CLI reads when no flag is
+passed — for that run only:
+
+```sh
+elgora-cli guardian:judgeable                        # the default deployment
+elgora-cli claim --network base-sepolia 7            # one invocation, by name
+elgora-cli claim --network 84532 7                   # the same, by chain id
+```
+
+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.
+
+Commands that use the public API accept `--api-base-url <url>`. That is a
+separate choice from the chain: it names one API deployment, and the flag wins
+over `ELGORA_API_BASE_URL` for that invocation. Point it at an API serving the
+deployment you selected.
+
+Protected API reads and writes use one EIP-712 approval per request. The
+signature is bound to the method, path, body, query, API host, and a recent
+chain block. The CLI constructs this approval locally; no session or stored API
+credential is required.
+
+`verification-record <bounty_id>` is the one exception: it is a plain,
+unauthenticated GET with no approval to sign. Deriving this advisory record
+grants no Poster, Guardian, coordinator, settlement, claim, or delivery
+authority, so there is nothing to authenticate — any caller, with or without a
+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:
+
+```sh
+pnpm --filter @elgora/cli typecheck
+pnpm --filter @elgora/cli test
+pnpm --filter @elgora/cli build
+pnpm --filter @elgora/cli build:standalone
+```
+
+The normal build uses workspace packages. The standalone build bundles the
+runtime for release readback.