This repository implements an end-to-end engineering prototype for the public-chain side of the Green Token methodology:
- selective-disclosure-oriented credential flow (BBS+ off-chain artifacts),
- L2 verification and minting on Arbitrum Sepolia,
- L1 anchor-only audit trail on Ethereum Sepolia via Arbitrum outbox,
- reproducible local and testnet benchmarking (including repeated runs with average/median/p95).
The project also contains legacy/local demo paths and OP-Stack style anchor contracts for comparison.
- Mints ERC-20 green-credit tokens on L2 after verifier-gated authorization.
- Enforces duplicate-prevention at contract level.
- Emits L2->L1 anchor messages and supports outbox monitoring/execution.
- Runs in both local deterministic mode and live Sepolia/Arbitrum Sepolia mode.
- Produces JSON benchmark artifacts suitable for reporting.
- Off-chain BBS+ issuance, presentation generation, and verification are implemented.
- Public-chain flow is implemented and benchmarked on real testnets.
- Current verifier harness for benchmark comparison is still non-production cryptographic semantics:
- SNARK track uses mock receipt/verifier semantics.
- Stylus-native track currently uses digest-approval semantics, not full native BBS+ pairing verification.
So this repo is a strong system-level and cost-baseline implementation, while full production cryptographic on-chain verification remains the next milestone.
BbsBls12381Verifier verifies real BBS proofs (IETF draft-06, BLS12-381-SHA-256) on-chain using the EIP-2537
precompiles (live on Arbitrum since ArbOS 51) and matches the IETF test vectors. GTokenL2BbsBoundArb mints from
proofs bound to one mint action (recipient, chain, contract, amount, nullifier, deadline) and credentials designated
by the issuer for one ledger. This closes mempool front-running, cross-ledger replay, cross-chain double issuance,
disclosure-set double minting and dedup collisions. The attack test suite reproduces each of these against the
paper's protocol. Design, security argument and gas results: docs/bbs_bound_minting.md.
npm run test:bbs:bound # IETF vectors + mint tests + attack matrix
npm run bench:bbs:bound:local # docs/bench_bbs_bound_local.json
npm run demo:bbs:bound # end-to-end walkthrough- Private/pre-validation domain (
contracts/private)
MetReg.sol: meter registry/status controls.DataVer.sol: commitment/verdict/VC-hash indexing.
- L2 execution domain (
contracts/l2)
GTokenL2*.sol: verifier-gated minting + duplicate prevention + L2->L1 message emission.GTokenL2BbsSnark*.sol: BBS-claim model mint path.
- L1 audit domain (
contracts/l1)
GTokenAnchor.sol: generic xDomain anchor pattern.GTokenAnchorArb.sol: Arbitrum bridge/outbox authenticated anchor pattern.
- Verifier contracts (
contracts/verifiers)
- mock SNARK/stylus verifier contracts for controlled measurement.
- RISC Zero adapter interface scaffold.
- Stylus workspace (
stylus/)
- native Rust verifier workspace and deploy tooling.
BbsDisclosedClaims:
reTypeCode(uint16)qtyKWh(uint256)readingTimestamp(uint64)credentialIdHash(bytes32)expiry(uint64)
Duplicate-prevention key:
usedCredential[credentialIdHash]
Anchor claim key:
claimId = keccak256(credentialIdHash, reTypeCode, qtyKWh, readingTimestamp)
contracts/: Solidity contracts (private/L2/L1/interfaces/mocks/verifiers)scripts/: deployment, flow orchestration, benchmark, outbox utilitiestest/: Hardhat test coveragestylus/: Rust Stylus projects and scaffoldingdataset/: generated VC/presentation artifactsdocs/: benchmark/outbox/report JSON and LaTeX report
- Node.js (LTS recommended)
- npm
- For Stylus native deployment path:
- Rust + Cargo
cargo-stylus
npm installnpm run clean
npm testOptional local demos:
npm run demo:v2
npm run demo:arb:mock
npm run gas:v2Create local config:
cp .env.example .envMinimum required for Arbitrum Sepolia automation:
DEPLOYER_PRIVATE_KEYSEPOLIA_RPC_URLARBITRUM_SEPOLIA_RPC_URLARBITRUM_L1_BRIDGE
Common optional variables:
ISSUER_PRIVATE_KEY,HOLDER_PRIVATE_KEYBENCH_RECIPIENTRUN_SNARK_MOCK,RUN_STYLUS_SIMSTYLUS_NATIVE_VERIFIER(use deployed stylus verifier instead of solidity mock)BENCH_REPEAT_COUNTand repeat-path overrides
Reference: docs/bbs_l2_runbook.md
- Real keys and RPC URLs go only in
.env, which is git-ignored..env.exampleholds placeholders only. - Use a dedicated testnet-only wallet for
DEPLOYER_PRIVATE_KEY, never one that holds mainnet funds. npm installenables a pre-commit hook (.githooks/pre-commit) that blocks commits containing private keys, RPC URLs with API keys, secret-key JSON fields or tracked.envfiles. To scan the whole tree, runnpm run check:secrets.- Scripts write only the RPC host to reports (
scripts/lib/redact.ts), never the full URL. They never write BBS issuer secret keys to disk. The Stylus deploy passes the key tocargo stylusthrough an owner-only temporary file, not the command line. - If a credential is ever committed, treat it as compromised: rotate it first, then remove it from history.
npm run bbs:issue:vc
npm run bbs:create:presentation
npm run bbs:verify:presentationOutputs:
dataset/bbs_vc.jsondataset/bbs_presentation.json
npm run flow:bbs:arb:autoThis flow:
- Builds/validates BBS artifacts off-chain.
- Deploys needed L1 and L2 contracts.
- Executes verify estimate, mint, transfer on L2.
- Emits L2->L1 message metadata.
- Writes machine-readable benchmark output.
Default output:
docs/bench_bbs_l2_arb_sepolia_auto.json
Deploy:
npm run deploy:stylus:bbs:verifierOutput:
docs/stylus_bbs_verifier_deploy.json
Then run automated flow with that verifier:
STYLUS_NATIVE_VERIFIER=0x<deployed_stylus_verifier> npm run flow:bbs:arb:autoPath labels in outputs:
solidity-snark-mock-arbstylus-native-sim-arb(default mock stylus verifier)stylus-native-arb(whenSTYLUS_NATIVE_VERIFIERis provided)
npm run bench:bbs:arb:repeat
npm run bench:bbs:arb:repeat:20
npm run bench:bbs:arb:repeat:50Output:
docs/bench_bbs_l2_arb_sepolia_repeat.json
Includes per-operation:
- sample count
- average gas
- median gas
- p95 gas
- average fee (wei/ETH)
Check whether messages are executable on L1:
npm run check:arb:outboxExecute confirmed messages:
npm run exec:arb:outboxOutputs:
docs/arb_sepolia_outbox_status.jsondocs/arb_sepolia_outbox_execute.json
Status model:
UNCONFIRMED: not yet executableCONFIRMED: executable nowEXECUTED: already executed
npm run bench:bbs:localOutput:
docs/bench_bbs_l2_local.json
Core quality and build:
npm testnpm run buildnpm run clean
Core BBS flow:
npm run flow:bbs:arb:autonpm run bench:bbs:arbnpm run bench:bbs:arb:repeatnpm run check:arb:outboxnpm run exec:arb:outbox
Deploy helpers:
npm run deploy:l1:arbitrumnpm run config:l1:arbitrumnpm run deploy:l2:bbs:snark:mocknpm run deploy:l2:bbs:stylus:simnpm run deploy:l2:bbs:risc0npm run deploy:stylus:bbs:verifier
Legacy/local demo helpers:
npm run demo:v2npm run demo:arb:mocknpm run gas:v2
- Duplicate mint prevention at contract state level.
- Expiry/freshness checks in mint authorization path.
- L1 remains anchor-only (no active L1 mint path).
- Arbitrum outbox sender authentication on L1 anchor execution.
- L2 mint/transfer and L1 anchor execution are separate lifecycle steps.
- Repeated benchmarks are more reliable than single-run snapshots.
- Testnet fees are engineering indicators, not mainnet commitments.
- Current verifier harness costs are not final production-crypto costs.
This is expected during repeated benchmarks. One logical action can trigger many RPC calls:
eth_chainIdeth_estimateGas- nonce/fee calls
eth_sendRawTransaction- repeated receipt polling
Repeated benchmark loops amplify this substantially.
Expected until Arbitrum confirmation/challenge lifecycle passes. Keep checking status with:
npm run check:arb:outboxIf flow fails around bridge/outbox checks, verify ARBITRUM_L1_BRIDGE is the correct Sepolia bridge contract address.
- Ensure
cargoandcargo stylusare installed. - Ensure wallet has Arbitrum Sepolia ETH.
- If fee errors occur, tune
STYLUS_MAX_FEE_GWEI.
- Runbook: docs/bbs_l2_runbook.md
- Project report (LaTeX): docs/report.tex
- Benchmark outputs:
docs/bench_bbs_l2_*.json
To reach paper-faithful production cryptographic path on public chain:
- integrate real on-chain RISC Zero receipt verification or full native Stylus BBS+ verification semantics,
- remove digest-approval benchmark semantics from critical path,
- rerun repeated benchmarks and update comparative cost report.