argus-mint

Provenance tokens for game assets. argus-mint renders art from reviewed templates, pins it to IPFS, builds canonical ERC-721 metadata, mints transferable cards and soulbound deeds, and anchors commit/reveal secrets and Merkle roots on-chain so anyone can check a game's records.

It contains no game logic. A consumer supplies a template's variables, a record to show, and 32-byte leaf hashes; argus-mint does the rest. Tokens carry no in-game power, and nothing pays out.

Part of the Argus suite.

Status: pre-alpha. Milestones M0–M5 are done: pure core, contracts, clients, JS verifier, and a live demo on Base Sepolia, plus a pre-review demo on Base mainnet (below). Renders go through argus-darkroom.

What's in the box

Install

uv pip install argus-mint            # pure Python core
uv pip install "argus-mint[chain]"   # + web3 for the indexer and ledger client
uv pip install "argus-mint[cli]"     # + the argus-mint command

Quick look

argus-mint templates templates/                 # validate templates, show status and hash
argus-mint mint --template my-approved.yaml \
  --var role=ranger --var colour=none --var pose=standing --seed 81234 \
  --asset unit-17 --to 0x7099…79C8 --name "Hana of the Strait" \
  --card 0x5FbD…0aa3 --chain-id 31337 --dry-run  # prints metadata, voucher and signature

from argus_mint import merkle, templates, vouchers
from argus_mint.metadata import card_metadata, content_hash

tree = merkle.build(leaf_hashes)            # OpenZeppelin StandardMerkleTree-compatible
proof = tree.proof(3)                       # verifies in Ledger.verify and MerkleProof.verify

Develop

Needs uv, Foundry and Node (for fixtures and the verifier).

git clone --recurse-submodules https://github.com/smk762/argus-mint
make install       # submodules + venv with all extras
make check         # lint + pytest + forge test
make help          # everything else

Versions are derived from git tags via hatch-vcs. Tagging vX.Y.Z publishes to PyPI.

Deploy (Base)

cp .env.example .env                        # RPC URLs and role addresses (no paid API keys needed)
cast wallet new deployer                    # new key, straight into Foundry's encrypted keystore; fund its address
make deploy                                 # Base Sepolia; `make deploy NETWORK=base` for mainnet

The script deploys Card, Deed and Ledger over plain JSON-RPC, grants roles, and verifies the sources on Sourcify for free (Blockscout displays them). VERIFIER=blockscout verifies on Blockscout directly; VERIFIER=etherscan uses Basescan and needs an Etherscan API key. Step by step, including wallet backup, funding and role setup: docs/deploy.md.

Rendering with argus-darkroom, pinning with Kubo

make ipfs                                    # local Kubo node (compose.yaml): RPC 127.0.0.1:5001, gateway :8080
argus-mint preflight my-template.yaml --darkroom http://localhost:8106      # reviewer check, every combination
argus-mint mint --template my-template.yaml --var ... --asset unit-17 --to 0x… --name "…" --card 0x… \
  --darkroom http://localhost:8106 --ipfs-api http://127.0.0.1:5001         # live: renders, pins, signs

On-chain, each step signs with a Foundry keystore account (--account / $ARGUS_MINT_ACCOUNT) or $ARGUS_MINT_SIGNER_KEY:

argus-mint submit demo-1.json                                         # send the voucher to Card.mint
argus-mint freeze --card 0x… --token-id 1 --uri <metadata cid>        # fix tokenURI at ipfs://…
argus-mint anchor leaves.txt --ledger 0x… --epoch 1 --tree epoch-1.json   # Merkle root into the Ledger

The Kubo RPC port is an admin API and is published on localhost only. Swarm port 4001 is public so wallets and gateways can fetch pinned art; behind NAT, pin on a VPS (native Kubo, reached through an SSH tunnel) (docs/deploy.md §6) so cards stay retrievable when this host is offline.

Live demo (Base Sepolia)

Deployed 2026-11-08 from this repo (make deploy), source verified on Sourcify:

Card #1 was made end to end. Every command's output is in demo/base-sepolia/.

1. Render. The approved example-portrait v1 template was rendered with fixed values and seed 42: portrait of a female dwarf, bronze heraldry, mining, cave, …. darkroom passed it on the first attempt under its SFW default policy (record cb2bd951…).
2. Pin. The image and canonical metadata were pinned on Kubo. The metadata's provenance carries the template hash, seed and attempt count.
3. Sign. A mint voucher was signed for the Card (EIP-712), carrying contentHash = keccak256 of the metadata's image and provenance.
4. Submit minted token 1.
5. Freeze fixed tokenURI(1) at ipfs://bafkreid3o6zha6adg7ndl4rpmnsv7bc22t6ak2ik4opr6oed56v74uhefu.

Epoch 1 anchor: four demo records (records.txt) were hashed with sha256 into a Merkle tree. Its root, 0x4cafc06c…1ee1f736, was anchored in the Ledger.

Verify it yourself

Anchored records, with the JS verifier and the public RPC (needs only Node):

make verifier-install
node demo/base-sepolia/verify.mjs          # each record checks out; a changed one is rejected

To check the card, read tokenURI(1) and contentHashOf(1) from the Card and fetch the metadata from IPFS. Then confirm keccak256(canonical({image, provenance})) equals the on-chain contentHash:

from argus_mint import chain
from argus_mint.metadata import content_hash
card = chain.contract(chain.connect("base-sepolia"), "Card", "0xCAa3573b5550870A5e15C47c650b8700D70a8fA7")
# doc = the JSON at card.functions.tokenURI(1).call()
assert content_hash(doc) == bytes(card.functions.contentHashOf(1).call())

Demo on Base mainnet (pre-review)

The same script was deployed to Base (8453) on 2026-11-08. It was the deployer's first transaction there, so the addresses equal the testnet ones, and all three contracts are verified on Sourcify. This is a demo: the contracts and deployment get a review before anything goes live, and the deployer still holds every role.

Six cards were rendered fresh from the approved example-portrait v1 template, one darkroom attempt each. They were pinned on a VPS Kubo node, minted and frozen by demo/base/mint-batch.sh, and every step's output is in demo/base/. Each card's on-chain contentHash matches its pinned metadata.

The collection is also on OpenSea. The same contentHash check as above works with chain.connect("base").

License

MIT