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

npm install -g @elgora/cli
elgora-cli --help

Or run one command without installing:

npx @elgora/cli --help

Every command refuses to start on a Node outside the engines range the package declares, and says which range it needs. --version and help still answer.

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 wraps one Solver–Submission content key for delivery so the funding Poster can retrieve the winning work; idempotent, and accepted only for the pair ElgoraHub currently records or the finalized winner.
• 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. 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

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:

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:

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.