regen-agent-kit

Drive the Regen Network chain (regen-1) with your OWN plain EVM key — no Keplr, no mnemonic, no new wallet.

This is a self-contained kit — npm install regen-agent-kit (or npx it with zero install, or copy the folder). Point it at your own secp256k1 key and an AI agent can act on Regen Ledger cold from this one README. It gives an agent two powers plus a trust primitive:

1. Govern — submit and vote on Regen's Cosmos governance (regen-1). Governance is the one Regen channel that still moves: permissionless, proposals pass on a cadence.
2. Supply — turn a settled EcologicalWorkProtocol (EWP) work packet on Base mainnet into a verifiable ecological-data claim anchored and attested on Regen Ledger's x/data module. This is the field-MRV (measurement / reporting / verification) supply that credit issuance is starved for — real work with proof becomes credit-grade data.
3. Verify — anyone can recompute a claim's hash/IRI from public Base state (no key, no trust in you) and confirm an anchor is honest. This is what makes the bridge trustable.

Regen is the credibility layer: persistent, on-chain, provable ReFi. Governing it keeps the economics sane; feeding it verified work is the frontier — your work becomes Regen's credit supply, their rails become demand for your work.

The crypto in this kit is proven against the live chain and must not be changed. The hash recipes, protobuf wire encoding, and IRI derivation are byte-for-byte verified against regen-1. npm run selftest re-proves it live. Change the encoding and the bridge silently produces hashes the chain will not recognize — worthless anchors. If you fork it, keep src/regen-data-proto.ts and the hashing paths exactly as they are.

The one idea that makes this work

Cosmos and Ethereum both use secp256k1. So your existing Base/Ethereum private key IS a valid Regen account — you just wrap it with a different address prefix:

DirectSecp256k1Wallet.fromKey(rawKey, "regen")  →  a valid regen1… account

No Keplr extension, no seed phrase, no second wallet to fund and secure. The same key that signs your Base transactions signs your Regen governance votes and x/data anchors. Run npm run address to see the regen1… address your key derives (deterministic, offline).

Key-safety model (read this first)

The method here is fully shareable. The key never is.

• Read-only commands need no key at all and run anywhere: address, balance, draft, status, claim, hash, graph, verify, selftest. Everything you need to inspect, preview, and prove is free and keyless.
• Only broadcasts need the key, and they read it from .env on the machine you run on. The wrappers (bin/gov.sh, bin/regen.sh) source your key into the tool's subprocess only — it is never printed, never logged, never passed as a CLI argument, never returned.
• Sign only where the key lives. An agent drives the chain by running these commands on the machine that holds the key — it does not receive the key. Your agent runs this code with your key; someone else's agent runs the same code with their key. Nobody ever hands a key to anyone.
• The env var is named ZORA_SIGNER_PRIVATE_KEY for drop-in parity with the repo this kit was extracted from. It just means "the signer key this kit reads." Point it at your key.

Never paste a real key into a prompt, a log, an issue, or a commit. .env is git-ignored; only .env.example (placeholders) is tracked.

Read-only by default · broadcasts are double-gated

| Mode | Commands | What it costs | How it's armed | |---|---|---|---| | Read-only (safe) | address balance draft status claim hash graph verify selftest simulate* | Nothing. No key**, no broadcast, no state change. | Just run it. Default. | | Gated broadcast (L4) | submit vote launch (governance) · anchor attest (x/data) | Real REGEN + a permanent public on-chain write. | The key and REGEN_GOV_SUBMIT_LIVE=true / REGEN_ANCHOR_LIVE=true. |

* simulate asks the chain to check-run an anchor (gas estimate, no broadcast). It needs the key to build the tx but writes nothing, so it is not behind the live flag. ** simulate is the only read-only command that needs the key.

Broadcasts refuse to run unless you explicitly set the live flag for that action, every time. There is no cron path, no "remember my choice." This kit ships pointed at safe.

Quickstart

Fastest — zero install. Any agent can prove the crypto and inspect real work with nothing but Node on PATH:

npx regen-agent-kit selftest   # ✓ MATCH — reproduces a real regen-1 graph hash
npx regen-agent-kit hash 14    # settled EWP work #14 → raw hash + regen:…json IRI
npx regen-agent-kit graph 14   # credit-grade graph hash + regen:…rdf IRI

As a dependency — install once, then call the regen-kit command:

npm install regen-agent-kit
npx regen-kit selftest
npx regen-kit gov status 64               # keyless: watch a live proposal's tally

From a clone — the same source, run in place:

cd regen-agent-kit        # or copy the packages/regen-agent-kit folder anywhere
npm install
npm run typecheck         # optional sanity check — should be clean
npm test                  # selftest + the work-#14 hash regressions, live against the chain
npm run hash 14           # the npm-script style also works: status 64, verify 14, graph 14, …

To act with YOUR key (only broadcasts need it):

cp .env.example .env      # then set ZORA_SIGNER_PRIVATE_KEY to YOUR key
npx regen-kit address     # the regen1… address your key derives (offline, deterministic)

Three run styles, all equivalent:

• regen-kit command (npx regen-kit … or the installed bin) — regen-kit hash 14, regen-kit gov balance, regen-kit anchor verify 14 <hash>. It routes a bare command to the right tool, or takes an explicit gov / anchor prefix.
• npm scripts (in a clone) — npm run status 64, npm run verify 14.
• Wrappers that auto-source your key from .env for broadcasts — bash bin/gov.sh balance, bash bin/regen.sh anchor hash 14. Use these for the gated writes so you never hand-manage the key.

No build step: the regen-kit bin (bin/regen-kit.mjs) runs the TypeScript in src/ directly via tsx (a bundled dependency). The source you read is exactly the code that runs.

Workflow 1 — Govern (src/regen-gov-from-evm.ts, wrapper bin/gov.sh)

Two proposal kinds, deliberately distinct:

• mint-params — a REAL, immediately-executable fix using the chain's stock Cosmos SDK x/mint module via MsgUpdateParams. No new code, no chain upgrade — it takes effect the moment it passes. This is the honest lever for validator economics (see the playbook below).
• signaling — an empty-messages[] text proposal that records community sentiment only. It executes nothing — there is no x/supply or custom mint module on regen-1 to run.

Commands

| Command | Key? | Broadcast? | What it does | |---|---|---|---| | npm run address | yes | no | Print the regen1… address your key derives. Offline, deterministic. | | npm run balance | yes | no | Live REGEN balance + gap to the 2000-REGEN gov deposit. | | npm run draft signaling / draft mint-params | yes* | no | Encode + preview the exact proposal that would broadcast (title, deposit, size, current→proposed params). | | npm run status 64 | no | no | Live status + vote tally (yes/no/abstain/veto) for a proposal id. | | … submit <kind> | yes | YES (L4) | Broadcast the proposal. Moves the 2000-REGEN deposit. | | … vote <id> <yes\|no\|abstain\|veto> | yes | YES (L4) | Cast a vote. | | … launch <kind> | yes | YES (L4) | Submit + auto-vote-YES in one shot (two txs). |

* draft/address/balance derive the address from the key but never touch the network for signing; status needs no key at all.

Gated ones require the live flag, e.g.:

REGEN_GOV_SUBMIT_LIVE=true bash bin/gov.sh submit mint-params
REGEN_GOV_SUBMIT_LIVE=true bash bin/gov.sh vote 64 yes

The proven playbook — "get the chain back on track"

1. Post a forum thread at forum.regen.network framing the ask.
2. draft mint-params and read it carefully. It right-sizes goal_bonded down to the actual bonded ratio so inflation can unpin from its ceiling, and trims inflation_max. (PROPOSED_MINT_PARAMS in the source is a starting point — confirm the exact targets for your network conditions before you submit.)
3. submit mint-params (2000 REGEN deposit) → note the proposal id.
4. vote <id> yes.
5. status <id> to watch the tally. Wire the forum URL into the proposal's metadata.

Why mint-params, not signaling: regen-1's live modules are x/data + x/ecocredit only. There is no x/supply/custom-mint module, so M012-style "hard cap" signaling passes but changes nothing. x/mint MsgUpdateParams is the real, stock, immediately-effective lever.

Workflow 2 — Supply the bridge (src/ewp-to-regen-anchor.ts, wrapper bin/regen.sh anchor)

A settled EWP packet on Base → a verifiable ecological-data claim on Regen x/data, signed from the same key. Anchoring records content-addressed provenance; attesting VOUCHES for the data on-chain — the credit-issuance-grade signal.

Two content-hash forms, both real:

• RAW — blake2b-256 of the canonical JSON claim (fileExtension json). Simple timestamp/provenance. Command family: hash → draft → anchor.
• GRAPH (credit-grade, attestable) — the claim as JSON-LD, hashed as blake2b-256 of the URDNA2015-canonicalized N-Quads. This is the RDF form Regen queries and issues credits from, and the only form MsgAttest accepts. Command family: graph → attest.

Commands

| Command | Key? | Broadcast? | What it does | |---|---|---|---| | npm run claim 14 | no | no | Read the settled packet from Base → print the EcologicalWorkClaim (incl. on-chain quality score). | | npm run hash 14 | no | no | Raw blake2b-256 ContentHash (hex/algo/ext) + resolvable regen:…json IRI. | | npm run graph 14 | no | no | Credit-grade graph hash (URDNA2015 → blake2b) + regen:…rdf IRI. | | bash bin/regen.sh anchor draft 14 | no | no | Encode the MsgAnchor protobuf; print typeUrl + size. No broadcast. | | npm run verify 14 [iri\|hash] | no | no | Recompute from PUBLIC Base state and MATCH/MISMATCH a claimed anchor. The trust primitive. | | npm run selftest | no | no | Re-prove the graph-hash recipe LIVE against a real regen-1 anchor (project C01-001). | | bash bin/regen.sh anchor simulate 14 | yes | no | Ask regen-1 to check-run the MsgAnchor (gas estimate). Nothing broadcast. Pre-flight. | | … anchor anchor 14 | yes | YES (L4) | Broadcast MsgAnchor (raw). Timestamped provenance. | | … anchor attest 14 | yes | YES (L4) | Broadcast MsgAnchor(graph) + MsgAttest(graph): anchor the RDF claim AND vouch for it. Credit-grade. |

Gated ones require REGEN_ANCHOR_LIVE=true, e.g.:

REGEN_ANCHOR_LIVE=true bash bin/regen.sh anchor simulate 14   # preflight — safe, writes nothing
REGEN_ANCHOR_LIVE=true bash bin/regen.sh anchor attest 14     # the real credit-grade write

The bridge refuses to anchor work that isn't SETTLED, and refuses any claim whose attested quality score can't be deterministically read (a missing field would make the content hash non-reproducible — the whole point of a content-addressed anchor).

The honest workflow

claim 14 → graph 14 → selftest (prove the recipe still reproduces the chain) → anchor simulate 14 (prove the chain accepts the message) → only then REGEN_ANCHOR_LIVE=true … anchor attest 14. Never anchor a hash a third party can't recompute.

VERIFIED recipes — cracked from real chain data, do not change

• Raw hash: blake2b-256 of the canonical JSON claim (keys sorted, whitespace-free).
• Graph hash: blake2b-256( UTF-8( jsonld.canonize(doc, {algorithm:"URDNA2015", format:"application/n-quads"}) ) ) — the trailing newline is KEPT. Blank nodes are ILLEGAL on Regen; the claim uses a single @id with literal values, so it has none. ContentHash_Graph = { digest BLAKE2B_256 = 1, canon RDFC_1_0 = 1, merkle NONE = 0 }.
• ContentHash oneof wire format: raw = field 1, graph = field 2. (Hand-encoded in src/regen-data-proto.ts, byte-for-byte identical to @regen-network/api's output.)
• IRI: regen:{base58check_v0(payload)}.<ext> where base58check is version-0 prefix + double-sha256 checksum:
  • raw payload = [0x00, digest, …hash], ext from file type (.json)
  • graph payload = [0x01, canon, merkle, digest, …hash], ext .rdf
• x/data is v2, not v1: /regen.data.v2.MsgAnchor, /regen.data.v2.MsgAttest.

Known-good regression values (recompute these to confirm nothing drifted)

• selftest → reproduces regen-1 project C01-001's on-chain graph hash 2d6cf47b9d750071918de4c743385e7a2065ae1148c5e549804b2ea9c73ec1f8 and prints ✓ MATCH.
• Settled EWP work #14 anchors deterministically:
  • raw hash: ca65b763d4260f80d22ec8d9150bdfd2b010be07fe9073a275c8dfe46dabf1b2
  • graph hash: ff428e0237cbb5459883630ed1fcd9d9b2bf073c23109304f866dabcf8d88bd9

If npm run hash 14 / npm run graph 14 ever print different values, something is broken — do not anchor; fix the drift first.

Landmines (already hit for you)

• Sign where the key lives. Read-only work runs anywhere; broadcasts must run on the machine holding the key. balance reports whether a key is present.
• MsgVote out-of-gasses under cosmjs "auto" (observed 52482 wanted vs 53949 used, code 11 WriteFlat). The kit uses explicit fixed gas (250000) for votes. submit's "auto" is fine.
• Governance weight = BONDED stake only. Liquid REGEN votes at ~0 weight. Your vote is recorded but counts for nothing in the tally unless the REGEN is delegated/staked.
• min_deposit is 2000 REGEN (2000000000 uregen). Older docs saying "500 REGEN" are stale.
• Signaling executes nothing. No x/supply/custom-mint module exists on-chain. Use x/mint MsgUpdateParams (the mint-params kind) for anything that must actually take effect.
• x/data is v2, not v1. Use the v2 message types (the live traffic is 100% v2). MsgAnchor / MsgAttest also under-shoot on "auto" gas — the kit sets explicit gas (~200k anchor, ~300k anchor+attest).
• The graph hash MUST reproduce the chain's, or the bridge is worthless. Run selftest (it checks against a real regen-1 anchor) before anchoring any graph. Keep the trailing newline. Never anchor a hash a third party can't recompute — that's what verify is for.
• Attest needs a GRAPH content hash, not raw. You cannot attest raw bytes. The credit-grade path is graph/attest, not hash/anchor.
• Funding path: bridge REGEN to your regen1… address (e.g. bridge.eco bridges axlREGEN ↔ REGEN), then confirm with balance before any submit/vote.

L4 gates (explicit human GO, every time — never a cron)

submit / vote / launch (governance, moves the 2000-REGEN deposit) and anchor / attest (x/data writes) all broadcast on-chain. Each is double-gated: the key and its live env flag (REGEN_GOV_SUBMIT_LIVE / REGEN_ANCHOR_LIVE). Everything else is read-only and free.

Dependencies (safe set — pinned on purpose)

@cosmjs/proto-signing  0.39.0
@cosmjs/stargate       0.39.0
cosmjs-types           0.11.0
@noble/hashes          ^1.8.0   (subpaths ./blake2b, ./sha256)
ethers                 5.8.0    (v5 API: ethers.providers.JsonRpcProvider — HTTP only)
jsonld                 8.3.3
tsx                    4.22.4   (runs the TS source directly — no build step, no compiled dist)
undici                 ^6.27.0  (npm "overrides" — pins any transitive undici to a safe line)

typescript + @types/node are devDependencies (only npm run typecheck needs them; the runtime does not). ethers v5 is used HTTP-only (JsonRpcProvider), so the ws WebSocket-transport advisory that npm audit flags on @ethersproject/providers is never on a code path this kit executes; the installed ws is already a patched line. Moving to ethers v6 is a breaking API change that would risk the verified hashing pipeline, so it is deliberately pinned at v5.

Do NOT add @regen-network/api. It bundles an old cosmjs whose cosmjs-types pulls a protobufjs with a CRITICAL "arbitrary code execution" advisory marked no fix available — every version has the same old cosmjs, so there is nothing to upgrade to. This kit deliberately removed it and hand-defines the ~5 needed regen.data.v2 messages in src/regen-data-proto.ts against a safe modern cosmjs. Lighter, safer, portable — and byte-for-byte identical output.

File tree

regen-agent-kit/
├── package.json          name, deps (exact/safe), undici override, one-liner scripts, bin
├── tsconfig.json         NodeNext, noEmit typecheck
├── README.md             this manual
├── LICENSE               MIT
├── .env.example          placeholders only — never a real key
├── .gitignore            ignores node_modules + .env (secrets)
├── src/
│   ├── regen-data-proto.ts      hand-encoded regen.data.v2 messages (VERIFIED wire format)
│   ├── regen-gov-from-evm.ts    governance: address/balance/draft/status/submit/vote/launch
│   └── ewp-to-regen-anchor.ts   bridge: claim/hash/graph/verify/selftest/simulate/anchor/attest
├── bin/
│   ├── regen-kit.mjs     the `regen-kit` bin (npm/npx entry) — routes a command to the right
│   │                     tool and runs it via tsx; works from a clone or a tarball install
│   ├── regen.sh          key-injecting wrapper: regen.sh gov <cmd> | regen.sh anchor <cmd>
│   └── gov.sh            governance easy-button (auto-sources the key from .env)
└── examples/
    └── recipes.sh        copy-paste read-only recipes (safe; the gated ones are commented out)

test.mjs (repo-only, not shipped) is the npm test gate: it runs the shipped bin against the live chain and asserts the three known-good values below.

Already-built companions (don't reinvent)

Available to any Claude as MCP servers / public repos:

• regen-compute MCP — credit retirement as an API (browse_available_credits, retire_credits via credit card, retire_via_ecobridge to pay with 50+ tokens across 10+ chains, get_retirement_certificate, estimate_session_footprint).
• regen-koi MCP — the Regen knowledge graph (search, resolve_entity, get_full_document, sparql_query, search_github_docs). Start Regen research here.
• Repos: regen-ledger (the chain — modules are x/data + x/ecocredit only), agentic-tokenomics (WG).

Live proof

• Governance: proposal #64 on regen-1 — a mint-params fix (goal_bonded 67%→60%, inflation_max 10%→7%) — submitted + voted YES 2026-07-08 from a plain Base key.
• Bridge: the graph-hash recipe is verified byte-for-byte against real regen-1 data (selftest reproduces project C01-001's on-chain hash 2d6cf47b…); settled work #14 anchors deterministically (raw ca65b763…, graph ff428e02…).

Anchoring/attesting are the credible frontier: your verified ecological work becomes on-chain, provable credit supply. Govern the chain, feed it real work — from one key you already have.