Command-line tools

These scripts let people and systems work with Certichain without the web application. None of them needs the site to be running. Deployment and administration scripts (deploying contracts, handing over admin roles, timelock proposals) are documented in Deployment and scripts, and the full command list in Commands.

Tool	Run from	Purpose
verify-credential.ts	blockchain/	Verify a credential package, VC or Open Badge file, offline and optionally on chain
import:check	repository root	Check a bulk import file before issuing
access	blockchain/	Make an access identity, prove and submit a zero-knowledge access request
api:key	repository root	Make a verification API key
zk:public	repository root	Copy the hash-checked circuit files the browser prover needs
network:measure, network:report	blockchain/	Measure gas and calldata per operation and build a cost report

Credential verifier

blockchain/scripts/verify-credential.ts checks a file a holder gives you.

cd blockchain
npx ts-node scripts/verify-credential.ts credential.vc.json
npx ts-node scripts/verify-credential.ts credential.json --rpc https://sepolia.example.org --registry 0x4444444444444444444444444444444444444444

--rpc and --registry go together or not at all. A file with @context is read as a VC or Open Badge; otherwise it is read as a credential package.

File	Offline checks	With --rpc and --registry
Credential package	Digest of the signed fields, EOA signature	Registry equals the package's verifyingContract and the chain matches; anchor fields; issuer registered (the key in charge); signature, including ERC-1271 contract wallets
VC or Open Badge	Claims match the embedded package, id, details, EOA signature, expiry, the badge's standard proof	The credential is active

Exit codes: 0 valid, 1 not valid, 2 usage or other error. Formats: Credential package and Verifiable credential.

Offline means partial

Without --rpc the script cannot know whether the credential was revoked or the issuer is still registered. Use the on-chain mode, the verify page, or the REST API for a decision.

Import file check

npm run import:check -- students.csv --adapter csv --types "Diploma, Short course" --folder ./documents

Option	Meaning
<file>	The import file, at most 10 MB
--adapter	csv, json or template; when left out, json for a .json file and csv otherwise
--types	Extra record type names, numbered from 1000 in the order given, in addition to the built-in types
--folder	A folder of documents, so rows can be checked against the file names in it

It runs the same whole-file validation as the import page and prints counts and problems only, never the row contents. Exit codes: 0 no problems, 1 problems found, 2 usage or read error. See Import files and Bulk import.

Access tool

npm run access in blockchain/ drives zero-knowledge access from the command line, as the /access page does in the browser:

access identity new <file>        make an access identity and save its secrets to a new file
access identity show <file>       print the access code of a saved identity
access prove --identity <file> --credential <id> --caller <address> --rpc <url> --out <file>
access submit --proof <file> --rpc <url>   (the account is read from ACCESS_SUBMIT_KEY)

• It reads the access gate deployment from src/contracts/zk/deployment.<chainId>.json.
• New files are written with mode 0600 and refuse to overwrite an existing file.
• submit reads the sending account's key from ACCESS_SUBMIT_KEY and removes it from the process environment straight after.
• Error messages have RPC addresses removed.

submit sends a transaction. On a public network that spends gas and needs the account owner's decision. See Zero-knowledge access.

API key

npm run api:key -- partner-a

Prints three lines: the new key (32 random bytes, base64url), its SHA-256, and the entry to add to API_KEYS:

key: <43 characters, shown once>
sha256: <64 hex characters>
entry: {"id":"partner-a","sha256":"<64 hex characters>","tier":"standard"}

Give the key to the partner over a private channel and store only the entry in the deployment settings. The id must be 1 to 40 lowercase letters, digits or hyphens. See Verification API (server side).

Circuit files

npm run zk:public copies the circuit files of the browser prover into public/zk/. It takes each file from the local cache blockchain/.zk-artifacts or downloads it (at most 16 MB, 60 second timeout), and checks it against the SHA-256 hashes in src/lib/zk/circuit-hashes.json before writing. It runs automatically before npm run dev and npm run build.

Network cost tools

Used for the network evaluation (P4-S01):

Command	What it does
npm run network:measure	Replays each Certichain operation on the in-process Hardhat network and writes gas used and calldata size to docs/network/operations.json
npm run network:report	Combines operations.json with dated fee readings in docs/network/fee-levels.json and writes docs/network/cost-report.md

Fee readings missing as of 2026-10-24

docs/network/fee-levels.json is not in the repository yet, so network:report cannot run until dated fee readings are added. operations.json is present.

Source files

• blockchain/scripts/verify-credential.ts
• scripts/import-check.ts, src/lib/import/check-cli.ts
• blockchain/scripts/access.ts, blockchain/scripts/lib/access-cli.ts
• scripts/api-key.mjs
• scripts/zk-public.mjs, src/lib/zk/circuit-hashes.json
• blockchain/scripts/measure-operations.ts, blockchain/scripts/network-report.ts, docs/network/README.md

Tests

• blockchain/test/v03/VerifyCredential.test.ts, blockchain/test/v03/VerifyVc.test.ts (verifier script)
• blockchain/test/zk/AccessCli.test.ts (access tool)
• blockchain/test/gas/OperationRecords.test.ts (operation records)
• src/lib/import/check-cli.test.ts and the other src/lib/import/*.test.ts files (import check)
• E2E: e2e/journeys/bulk-import.journey.ts, access-proof.journey.ts