{"id":50776233,"url":"https://github.com/cardanowall/label-309-cli","last_synced_at":"2026-06-12T00:01:22.676Z","repository":{"id":362058770,"uuid":"1256469913","full_name":"cardanowall/label-309-cli","owner":"cardanowall","description":"Command-line standalone Label 309 verifier and toolkit (cardanowall), built on the Rust SDK.","archived":false,"fork":false,"pushed_at":"2026-06-11T12:09:42.000Z","size":1063,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T14:08:23.148Z","etag":null,"topics":["cardano","cip-309","cli","proof-of-existence","rust","timestamping","verifier"],"latest_commit_sha":null,"homepage":"https://label309.org","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cardanowall.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-01T20:07:39.000Z","updated_at":"2026-06-11T12:10:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cardanowall/label-309-cli","commit_stats":null,"previous_names":["cardanowall/cip309-cli","cardanowall/label-309-cli"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/cardanowall/label-309-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cardanowall%2Flabel-309-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cardanowall%2Flabel-309-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cardanowall%2Flabel-309-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cardanowall%2Flabel-309-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cardanowall","download_url":"https://codeload.github.com/cardanowall/label-309-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cardanowall%2Flabel-309-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34222709,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cardano","cip-309","cli","proof-of-existence","rust","timestamping","verifier"],"created_at":"2026-06-12T00:00:37.085Z","updated_at":"2026-06-12T00:01:22.667Z","avatar_url":"https://github.com/cardanowall.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `cardanowall` — Label 309 standalone verifier \u0026 Proof-of-Existence CLI\n\nA single, fast, dependency-free native binary for working with **Label 309 Proof\nof Existence** on Cardano: verify a record, anchor a new one, sign off-host,\nderive an identity from a seed, build/verify Merkle proofs, and read a sealed\ninbox.\n\nIt is **gateway-agnostic**. Every networked command takes an explicit gateway\nbase URL and an opaque API key — the CLI is bound to no particular operator. The\nhosted `cardanowall.com` service is one such gateway; any server that implements\nthe Label 309 gateway API works the same way. **`verify` needs no gateway operator\nat all** — it talks only to public Cardano explorers (Koios/Blockfrost) and\npublic Arweave/IPFS gateways, so a proof can be checked with zero trust in the\nissuer, their domain, or their server.\n\nBuilt on the Rust Label 309 SDK (the `cardanowall` crate); a byte-parity twin of\nthe TypeScript and Python SDKs.\n\n---\n\n## Install\n\n### From source (today)\n\n```bash\n# A release binary at target/release/cardanowall:\ncargo build --release\n\n# …or install `cardanowall` onto your PATH:\ncargo install --path .\ncardanowall --version          # cardanowall \u003cver\u003e (git \u003csha\u003e, built \u003cdate\u003e)\n```\n\nRequires a recent stable Rust toolchain. No Node, no runtime, no network access\nto install.\n\n### Prebuilt binaries / crates.io\n\nTagged releases publish the crate to crates.io and attach prebuilt\nper-platform binaries:\n\n```bash\ncargo install cardanowall-cli   # installs the `cardanowall` binary\n```\n\nUntil the first tagged release, build from source as above.\n\n---\n\n## Quick start\n\n```bash\n# Inspect an identity derived from a 32-byte seed (offline, no network):\nprintf '%s' \"$SEED_HEX\" | cardanowall identity --seed-stdin\n\n# Verify a proof against a public Cardano explorer (no operator server):\ncardanowall verify \u003ctx-hash\u003e --cardano-gateway https://api.koios.rest/api/v1\n\n# Save a gateway once, then anchor a file's hash through it:\ncardanowall gateway add prod --base-url https://cardanowall.com   # prompts for the key\ncardanowall submit --file ./contract.pdf --seed-stdin \u003c\u003c\u003c\"$SEED_HEX\"\n```\n\n---\n\n## Commands\n\nRun `cardanowall \u003ccommand\u003e --help` for the full, authoritative flag list.\n\n### `verify \u003ctx-hash\u003e`\n\nStandalone verification of the Label 309 record at a Cardano transaction. Fetches\nthe metadata from a public explorer, runs structural validation, checks record\nsignatures, and (with a recipient key) decrypts and re-hashes a sealed payload.\n\n```bash\ncardanowall verify \u003ctx-hash\u003e \\\n  --cardano-gateway https://api.koios.rest/api/v1 \\   # repeatable; Koios-compatible\n  --blockfrost \u003cproject-id\u003e \\                          # optional fallback\n  --profile signed \\                                   # core | signed | sealed | recipient-sealed\n  --json --pretty\n```\n\nSealed proofs: pass `--secret-key \u003chex\u003e` (or `--secret-key-file` / `--secret-key-stdin`,\nrepeatable) to decrypt and recompute plaintext hashes. The keyring is global to\nthe run — every supplied key is tried against every sealed item.\n`--no-fetch` suppresses content fetches (item URIs, sealed ciphertext, Merkle\nleaves-lists) — unfetched claims report as not checked. The transaction itself is\nstill resolved from the Cardano gateway chain, so structural validation and\nsignature checks run against the real on-chain record.\n\n### `submit`\n\nAnchor a new PoE through a gateway. Mutually exclusive modes:\n\n```bash\ncardanowall submit --hash \u003c64-hex-digest\u003e          # anchor a precomputed sha2-256 digest\ncardanowall submit --file ./doc.pdf                # hash the file, then anchor\ncardanowall submit --merkle ./leaves.txt           # build a Merkle tree, anchor root + leaves\n```\n\nAdd `--seed` (or the safe variants below) to attach an Ed25519 record signature;\nomit it to publish unsigned. Requires a gateway (`--base-url` + `--api-key`, env,\nor a saved profile). `--alg blake2b-256` switches the content hash.\n\n### `sign record | prepare | assemble`\n\nOff-host PATH-1 (identity Ed25519) COSE signing — for air-gapped signing where the\nkeys never touch the gateway.\n\n```bash\ncardanowall sign record  --seed-stdin --in record.cbor --json   # sign in one step\ncardanowall sign prepare --signer-pubkey \u003chex\u003e --hash \u003chex\u003e     # emit the sig-structure to sign elsewhere\ncardanowall sign assemble --signer-pubkey \u003chex\u003e --signature \u003chex\u003e --in record.cbor\n```\n\n### `identity --seed`\n\nDerive and print the public identity from a 32-byte master seed: Ed25519/X25519/\nX-Wing public keys, both age recipient strings, and a short display fingerprint.\nFully offline; no network, no API key. `--json` emits the full X-Wing key.\n\nThe seed is accepted in either representation, here and on every other command:\n64-digit raw hex (`0x` prefix and whitespace tolerated) or the checksummed\n`L309-SEED-1…` bech32 form in a single case (the lowercase twin is equally\nvalid; mixed case is rejected).\n\n### `merkle build | verify`\n\n```bash\ncardanowall merkle build  --in leaves.txt --json            # root + canonical leaves-list\ncardanowall merkle verify --root \u003chex32\u003e --leaf \u003chex32\u003e --proof proof.json\n```\n\n### `inbox sync | list | decrypt`\n\nDiscover, list, and decrypt sealed PoE addressed to your identity. Raw-seed-first:\nidentify with `--seed` (hex or `L309-SEED-1…`) or a raw `--secret-key \u003chex\u003e` (plus\nthe `-file`/`-stdin` variants) — never an account envelope.\n\n```bash\ncardanowall inbox sync   --seed-stdin\ncardanowall inbox list   --seed-stdin --json\ncardanowall inbox decrypt \u003ctx-hash\u003e --secret-key-stdin\n```\n\n`sync` persists a per-identity cursor under `~/.cardanowall/\u003cid\u003e/inbox.json`.\n\n### `gateway add | use | list | show | remove`\n\nNamed gateway profiles (an endpoint + its API key). This is configuration, not a\nlogin — the gateway API is key-based.\n\n```bash\ncardanowall gateway add prod --base-url https://cardanowall.com   # hidden key prompt\ncardanowall gateway add prod --base-url https://cardanowall.com --api-key-stdin \u003c\u003c\u003c\"$KEY\"  # for CI\ncardanowall gateway use prod\ncardanowall gateway list                 # keys masked\ncardanowall gateway show prod --reveal   # print the key\n```\n\n### `completion \u003cbash|zsh|fish|powershell\u003e`\n\nPrint a shell completion script to stdout.\n\n```bash\ncardanowall completion zsh  \u003e ~/.zfunc/_cardanowall\ncardanowall completion bash \u003e /etc/bash_completion.d/cardanowall\n```\n\n---\n\n## Secrets \u0026 safety\n\nSecrets are **never required as a command-line argument** — argv leaks into shell\nhistory, `ps`, and CI logs. Every command that needs a seed or recipient key\nresolves it in this order:\n\n1. `--seed-file \u003cpath\u003e` / `--secret-key-file \u003cpath\u003e` (read from a file)\n2. `--seed-stdin` / `--secret-key-stdin` (or the value `-`) — read from stdin\n3. the matching environment variable (see below)\n4. a **hidden interactive prompt** — only on a TTY, when the secret is required\n5. otherwise, a clear error pointing at options 1–3\n\nOn every path `--seed` accepts both seed representations — 64-digit raw hex or\nthe checksummed `L309-SEED-1…` form; `--secret-key` is a raw X25519 key and is\nhex-only.\n\nThe raw `--seed \u003cvalue\u003e` / `--secret-key \u003chex\u003e` flags still exist for throwaway/\ntest values (e.g. inspecting a public test vector with `identity`) but are\ndocumented as **insecure** and should not carry a real key.\n\nThe moderately-sensitive API key may be stored in a gateway profile; that file is\nwritten with `0600` permissions and the key is masked in `list`/`show`.\n\n---\n\n## Configuration \u0026 precedence\n\nConfig lives at `~/.cardanowall/config.toml` (override with `CARDANOWALL_CONFIG_PATH`),\nwritten `0600`:\n\n```toml\ndefault_gateway = \"prod\"\n\n[gateways.prod]\nbase_url = \"https://cardanowall.com\"\napi_key  = \"…\"                       # stored only if you saved one\n\n# Public data sources used by `verify` / `inbox` (each string or list):\ncardano_gateway = [\"https://api.koios.rest/api/v1\"]\narweave_gateway = \"https://arweave.net\"\nipfs_gateway    = \"https://ipfs.io\"\n```\n\nResolution precedence for every value: **explicit flag → environment variable →\nactive gateway profile → built-in default** (the built-in default applies to the\npublic data gateways only; a service `--base-url`/`--api-key` has no default).\n\n---\n\n## Environment variables\n\nConsistent across every command:\n\n| Variable                                   | Flag                | Meaning                          |\n| ------------------------------------------ | ------------------- | -------------------------------- |\n| `CARDANOWALL_BASE_URL`                     | `--base-url`        | service gateway base URL         |\n| `CARDANOWALL_API_KEY`                      | `--api-key`         | opaque bearer API key            |\n| `CARDANOWALL_SEED`                         | `--seed`            | seed (hex or `L309-SEED-1…`)     |\n| `CARDANOWALL_RECIPIENT_KEY`                | `--secret-key`      | X25519 recipient key(s)          |\n| `CARDANOWALL_CARDANO_GATEWAY`              | `--cardano-gateway` | Koios-compatible explorer URL(s) |\n| `CARDANOWALL_ARWEAVE_GATEWAY`              | `--arweave-gateway` | Arweave gateway URL(s)           |\n| `CARDANOWALL_IPFS_GATEWAY`                 | `--ipfs-gateway`    | IPFS gateway URL(s)              |\n| `CARDANOWALL_BLOCKFROST_PROJECT_ID`        | `--blockfrost`      | Blockfrost fallback              |\n| `CARDANOWALL_CONFIRMATION_DEPTH_THRESHOLD` | `--threshold`       | confirmation depth               |\n| `CARDANOWALL_DENY_HOST`                    | `--deny-host`       | extra egress deny-list entries   |\n| `CARDANOWALL_CONFIG_PATH`                  | —                   | override the config file path    |\n\n---\n\n## Automation \u0026 JSON\n\n- `--json` on any command emits machine-readable JSON on **stdout** (add `--pretty`\n  to indent). Data goes to stdout; diagnostics go to stderr — pipe-clean.\n- In `--json` mode, failures emit a structured error to **stderr**:\n  `{\"error\":{\"code\":\u003cexit\u003e,\"message\":\"…\",\"command\":\"…\"}}`.\n- `--no-color` / `--color \u003cauto|always|never\u003e` and `-q/--quiet` are global. Color\n  follows `NO_COLOR` / `CLICOLOR_FORCE` / TTY detection and is never emitted under\n  `--json`.\n- Provide secrets via env or stdin in CI; never on argv.\n\n## Exit codes\n\n| Code | Meaning                                                           |\n| ---- | ----------------------------------------------------------------- |\n| `0`  | valid / success                                                   |\n| `1`  | integrity-class failure (a cryptographic/structural check failed) |\n| `2`  | network-class failure (a fetch/transport error)                   |\n| `3`  | pending (insufficient confirmations)                              |\n| `4`  | CLI input error (bad arguments, missing required input)           |\n\n`verify` maps the verifier's verdict straight through to `0/1/2/3`.\n\n---\n\n## Service independence\n\n`verify` proves a record using only the transaction metadata, the (optional)\ncontent bytes, and a public blockchain explorer. It contacts no issuer server and\nhonors a deny-list so it cannot be steered back to a single operator. A proof you\nverified once stays verifiable by anyone, forever, with any Label 309 tooling.\n\n## Related repositories\n\nThis CLI is one of the Label 309 reference projects:\n\n- [`label-309`](https://github.com/cardanowall/label-309) — the Label 309 standard:\n  prose spec, CDDL, JSON schemas, registries, and the conformance vectors.\n- [`label-309-rs`](https://github.com/cardanowall/label-309-rs) — the Rust SDK crate\n  `cardanowall` this CLI is built on.\n- [`label-309-ts`](https://github.com/cardanowall/label-309-ts) — the TypeScript SDKs.\n- [`label-309-py`](https://github.com/cardanowall/label-309-py) — the Python SDK.\n\n## License\n\nApache-2.0.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcardanowall%2Flabel-309-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcardanowall%2Flabel-309-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcardanowall%2Flabel-309-cli/lists"}