argus-mint 0.1.0__tar.gz

argus_mint-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+# hatch-vcs writes this at build time (version derived from git tags)
+src/argus_mint/_version.py
+
+# Foundry
+contracts/out/
+contracts/cache/
+contracts/broadcast/*/31337/
+# JS (verifier + fixture generator)
+node_modules/
+# Local deploy settings (see .env.example)
+.env
+contracts/broadcast/**/*.lock

argus_mint-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project are documented here. Versions come from git tags (`hatch-vcs`).
+
+## Unreleased
+
+## 0.1.0 (2026-11-08)
+
+First public release, covering milestones M0–M5. Pre-alpha: the Python API may still change, and the contracts have not had an external review. The Base mainnet deployment is a demo, not a production deployment.
+
+### Added
+
+- Pre-review demo on Base mainnet: same contract addresses as testnet (deployer's first transaction), Sourcify-verified, six cards rendered fresh, pinned on a VPS node, minted and frozen by `demo/base/mint-batch.sh`.
+- `scripts/kubo-vps.sh`: native Kubo as a systemd service for a public pinning node. Docker port publishing (rootless especially) left the node unable to accept incoming connections, so gateways couldn't fetch new images.
+- M5 live demo on Base Sepolia: contracts deployed and Sourcify-verified, card #1 rendered through darkroom, pinned, minted and frozen, epoch 1 Merkle root anchored. Outputs and a JS verification script are in `demo/base-sepolia/`, and the README has the walkthrough.
+- On-chain CLI: `submit` (voucher → `Card.mint`), `freeze` (fix tokenURI at ipfs://), `anchor` (Merkle root → Ledger, with the tree dump). Each pre-checks what the contract would refuse and decodes custom-error reverts. `keys` module: Foundry keystore signers (password file for unattended use, or a hidden prompt) alongside `$ARGUS_MINT_SIGNER_KEY`; `mint --account`. `chain.send(value=)`, `chain.explain_revert`.
+- `compose.yaml` with a pinned Kubo node (`make ipfs` / `make ipfs-down`); the example template now names real darkroom models. Verified end to end: darkroom render → Kubo pin → metadata → signed voucher.
+- darkroom render client (`darkroom.DarkroomClient`): guarded generation over SSE with record and image-hash checks, outcomes mapped onto the retry protocol; `argus-mint preflight` checks every template combination before approval; live `mint` (`--darkroom`, `--ipfs-api`). Templates gain `sampling` and weighted LoRAs with trigger words.
+- Keyless RPC: public Base endpoints with `chain.connect()` failover; contract verification defaults to Sourcify (free), with Blockscout or Basescan as options.
+- Base as the target chain: `networks` module (Base 8453, Base Sepolia 84532), `mint --network`, Foundry RPC and Basescan verification config, `make deploy`, `.env.example`, and `Web3Rpc(head="safe"|"finalized")` for following OP Stack safe/finalized heads.
+- M4 verifier: ES module under `verifier/` (Merkle proofs, Ledger root/commitment/reveal reads over JSON-RPC, on-chain `verify` cross-check, drand quicknet BLS beacon verification), tested against OpenZeppelin and Python proof fixtures, real quicknet rounds, and JSON-RPC responses recorded from anvil.
+- M3 clients: `render` (darklight `Protocol`, safety rejections retried with sha256-derived seeds up to `max_attempts`, every attempt recorded; non-safety errors stop at once), `pin` (`Pinner` protocol, `KuboPinner` for a self-hosted node, `LocalPinner` for tests/dry runs), `ledger` (`LedgerClient`), `indexer` (stateless confirmed-blocks follower with deep-reorg detection, `Web3Rpc` adapter), `chain` helpers, and the CLI (`templates`, `mint --dry-run`).
+- M2 contracts: `Card` (ERC-721 + ERC-4906 + ERC-2981, EIP-712 voucher mint, live base URI then per-token freeze to `ipfs://`), `Deed` (ERC-721 + ERC-5192 soulbound, one deed per record id, holder may burn), `Ledger` (sha256 commit/reveal and Merkle-root anchors per epoch, write-once), `Deploy.s.sol`. Forge tests cover every revert, fuzz voucher fields and proofs, and consume Python-built fixtures; anvil-backed pytest mints a Python-signed voucher and verifies Python-built proofs on a live node.
+- Committed contract ABIs in `src/argus_mint/abi/` (`make abi`), checked against the build in CI.
+- M1 pure core: `templates` (registry, validation, `fill`; template hash excludes `status`), `metadata` (canonical ERC-721 JSON, `content_hash` over image + provenance), `merkle` (OpenZeppelin `StandardMerkleTree` `["bytes32"]` port with `standard-v1` dump/load), `vouchers` (EIP-712 `MintVoucher` for the `Card` contract), `siwe` (EIP-4361 build/parse/verify).
+- Merkle fixtures generated by `@openzeppelin/merkle-tree@1.0.8` (`make fixtures`) for 1, 2, 3, 7 and 1,000 leaves.
+- M0 scaffold: Python package from `argus-pkg-template`, Foundry project under `contracts/` with OpenZeppelin Contracts v5.4.0 and forge-std v1.17.0 as submodules, Makefile targets for both toolchains, standalone CI (Python + contracts).

argus_mint-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 smk762
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

argus_mint-0.1.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.5
+Name: argus-mint
+Version: 0.1.0
+Summary: Provenance tokens for game assets: render from reviewed templates, pin to IPFS, mint ERC-721 cards and soulbound deeds, and anchor commitments and Merkle roots on-chain
+Project-URL: Repository, https://github.com/smk762/argus-mint
+Project-URL: Homepage, https://github.com/smk762/argus-mint#readme
+Project-URL: Issues, https://github.com/smk762/argus-mint/issues
+Project-URL: Changelog, https://github.com/smk762/argus-mint/blob/main/CHANGELOG.md
+Project-URL: Argus suite, https://github.com/smk762?tab=repositories&q=argus
+Author: smk762
+License-Expression: MIT
+License-File: LICENSE
+Keywords: commit-reveal,eip-4361,eip-712,erc-5192,erc-721,ethereum,foundry,game-assets,generative-ai,ipfs,merkle-tree,nft,provenance,siwe,solidity,soulbound
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Framework :: Pydantic :: 2
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: eth-abi>=5.0
+Requires-Dist: eth-account>=0.13
+Requires-Dist: eth-utils>=5.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pycryptodome>=3.20
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: structlog>=24.0
+Provides-Extra: chain
+Requires-Dist: web3>=7.0; extra == 'chain'
+Provides-Extra: cli
+Requires-Dist: rich>=13.0; extra == 'cli'
+Requires-Dist: typer>=0.12; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff==0.15.16; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 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](https://github.com/smk762?tab=repositories&q=argus).
+
+> 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
+
+| Part | What it does |
+| --- | --- |
+| `argus_mint` (Python) | template registry, darklight render client with retries, IPFS pinning, canonical metadata, OpenZeppelin-compatible Merkle trees, EIP-712 mint vouchers, SIWE, a reorg-safe event indexer |
+| `contracts/` (Foundry) | `Card` (ERC-721 + ERC-4906 + ERC-2981, voucher mint), `Deed` (ERC-721 + ERC-5192 soulbound), `Ledger` (commit/reveal/anchor notary) |
+| `verifier/` (ES module) | verify Merkle proofs against a Ledger root, revealed secrets against commitments, and drand quicknet beacons |
+
+## Install
+
+```bash
+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
+
+```bash
+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
+```
+
+```python
+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](https://docs.astral.sh/uv/), [Foundry](https://book.getfoundry.sh/) and Node (for fixtures and the verifier).
+
+```bash
+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)
+
+```bash
+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](docs/deploy.md).
+
+## Rendering with argus-darkroom, pinning with Kubo
+
+```bash
+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`:
+
+```bash
+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](docs/deploy.md#6-pin-on-a-vps-optional)) 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:
+
+| Contract | Address |
+|---|---|
+| Card | [`0xCAa3573b5550870A5e15C47c650b8700D70a8fA7`](https://sepolia.basescan.org/address/0xCAa3573b5550870A5e15C47c650b8700D70a8fA7) |
+| Deed | [`0xe44D67bdFd3416F97206fdE7aeE55F9008EB5D7c`](https://sepolia.basescan.org/address/0xe44D67bdFd3416F97206fdE7aeE55F9008EB5D7c) |
+| Ledger | [`0x4b41B687C694bd8bf3778871752637445c2Aa254`](https://sepolia.basescan.org/address/0x4b41B687C694bd8bf3778871752637445c2Aa254) |
+
+**Card #1** was made end to end. Every command's output is in [demo/base-sepolia/](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](https://sepolia.basescan.org/tx/0x194f515824b65ff610fc61010ff01370745ed7c8a134cca2385d36bc080c5324)** minted token 1.
+5. **[Freeze](https://sepolia.basescan.org/tx/0x0f3140ec791db3069693ee9cb655f5ded8ca65b3bfcc33c9dfc7e4989de84bb4)** fixed `tokenURI(1)` at `ipfs://bafkreid3o6zha6adg7ndl4rpmnsv7bc22t6ak2ik4opr6oed56v74uhefu`.
+
+**Epoch 1 anchor:** four demo records ([records.txt](demo/base-sepolia/records.txt)) were hashed with sha256 into a Merkle tree. Its root, `0x4cafc06c…1ee1f736`, was [anchored in the Ledger](https://sepolia.basescan.org/tx/0x98899e0c2d074f0b63e30af5d7d52ee1ace470024932fa64124cdcda10584695).
+
+### Verify it yourself
+
+Anchored records, with the JS verifier and the public RPC (needs only Node):
+
+```bash
+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`:
+
+```python
+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](demo/base/mint-batch.sh), and every step's output is in [demo/base/](demo/base/). Each card's on-chain `contentHash` matches its pinned metadata.
+
+| Token | Name | Mint | Freeze |
+|---|---|---|---|
+| [1](https://basescan.org/nft/0xCAa3573b5550870A5e15C47c650b8700D70a8fA7/1) | Azure Knight | [tx](https://basescan.org/tx/0x595626d4645f5e067b8e1bd7c8b67cc2ea12c8051a5fb1846784659110496c30) | [tx](https://basescan.org/tx/0x39089c0f17410e044a407f0b9cf7d9125d5ecde71400200702e25df0669f6e50) |
+| [2](https://basescan.org/nft/0xCAa3573b5550870A5e15C47c650b8700D70a8fA7/2) | Emerald Wizard | [tx](https://basescan.org/tx/0x15a60342852c7f40f7ea283a55637195f102b69899bb82a2ff638f1130808bc8) | [tx](https://basescan.org/tx/0x52ead3396a533c8232ecab5540d61f9c3ef3d0bcbbf7b816aad1790088683b28) |
+| [3](https://basescan.org/nft/0xCAa3573b5550870A5e15C47c650b8700D70a8fA7/3) | Steel Cyborg | [tx](https://basescan.org/tx/0xfed072d1830d14c14bf4c60b912c079873e36cdfafc5bdb6cc6640e5b91d2a3e) | [tx](https://basescan.org/tx/0xa783b4aa35d4f382f1d19b21cb46377b70c83cb5a3a6c31f240d991e39935991) |
+| [4](https://basescan.org/nft/0xCAa3573b5550870A5e15C47c650b8700D70a8fA7/4) | Silver Huntress | [tx](https://basescan.org/tx/0xef0aecf8187f30aaa919f3fc48db4dfdd8a34aeb64485851c4ffff09d79a94ae) | [tx](https://basescan.org/tx/0x69af3f6c0ff486aae3f3aa2e63602e22e2c268382becec430a7eecaf7ea6c155) |
+| [5](https://basescan.org/nft/0xCAa3573b5550870A5e15C47c650b8700D70a8fA7/5) | Crimson Orc | [tx](https://basescan.org/tx/0xd3e4dde31bdec93d97d8ed469028eaddd1c98d8e1a33f40b6517cc3e04170858) | [tx](https://basescan.org/tx/0xc8c1b77f81b5b9338a37836d6905e60bb665b06b6d61c61bf4f75237d761ab16) |
+| [6](https://basescan.org/nft/0xCAa3573b5550870A5e15C47c650b8700D70a8fA7/6) | Golden Priest | [tx](https://basescan.org/tx/0x9c7d71c1e30d34eef8ba3e149800d70c7d44f5705127e69e5e81c6ea33d6b192) | [tx](https://basescan.org/tx/0x437f03b5ad49bab8b6505a02179277bce97b395c959518b1c801c923238c0008) |
+
+The collection is also on [OpenSea](https://opensea.io/collection/argus-mint-card). The same `contentHash` check as above works with `chain.connect("base")`.
+
+## License
+
+MIT

argus_mint-0.1.0/README.md

@@ -0,0 +1,145 @@
+# 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](https://github.com/smk762?tab=repositories&q=argus).
+
+> 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
+
+| Part | What it does |
+| --- | --- |
+| `argus_mint` (Python) | template registry, darklight render client with retries, IPFS pinning, canonical metadata, OpenZeppelin-compatible Merkle trees, EIP-712 mint vouchers, SIWE, a reorg-safe event indexer |
+| `contracts/` (Foundry) | `Card` (ERC-721 + ERC-4906 + ERC-2981, voucher mint), `Deed` (ERC-721 + ERC-5192 soulbound), `Ledger` (commit/reveal/anchor notary) |
+| `verifier/` (ES module) | verify Merkle proofs against a Ledger root, revealed secrets against commitments, and drand quicknet beacons |
+
+## Install
+
+```bash
+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
+
+```bash
+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
+```
+
+```python
+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](https://docs.astral.sh/uv/), [Foundry](https://book.getfoundry.sh/) and Node (for fixtures and the verifier).
+
+```bash
+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)
+
+```bash
+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](docs/deploy.md).
+
+## Rendering with argus-darkroom, pinning with Kubo
+
+```bash
+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`:
+
+```bash
+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](docs/deploy.md#6-pin-on-a-vps-optional)) 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:
+
+| Contract | Address |
+|---|---|
+| Card | [`0xCAa3573b5550870A5e15C47c650b8700D70a8fA7`](https://sepolia.basescan.org/address/0xCAa3573b5550870A5e15C47c650b8700D70a8fA7) |
+| Deed | [`0xe44D67bdFd3416F97206fdE7aeE55F9008EB5D7c`](https://sepolia.basescan.org/address/0xe44D67bdFd3416F97206fdE7aeE55F9008EB5D7c) |
+| Ledger | [`0x4b41B687C694bd8bf3778871752637445c2Aa254`](https://sepolia.basescan.org/address/0x4b41B687C694bd8bf3778871752637445c2Aa254) |
+
+**Card #1** was made end to end. Every command's output is in [demo/base-sepolia/](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](https://sepolia.basescan.org/tx/0x194f515824b65ff610fc61010ff01370745ed7c8a134cca2385d36bc080c5324)** minted token 1.
+5. **[Freeze](https://sepolia.basescan.org/tx/0x0f3140ec791db3069693ee9cb655f5ded8ca65b3bfcc33c9dfc7e4989de84bb4)** fixed `tokenURI(1)` at `ipfs://bafkreid3o6zha6adg7ndl4rpmnsv7bc22t6ak2ik4opr6oed56v74uhefu`.
+
+**Epoch 1 anchor:** four demo records ([records.txt](demo/base-sepolia/records.txt)) were hashed with sha256 into a Merkle tree. Its root, `0x4cafc06c…1ee1f736`, was [anchored in the Ledger](https://sepolia.basescan.org/tx/0x98899e0c2d074f0b63e30af5d7d52ee1ace470024932fa64124cdcda10584695).
+
+### Verify it yourself
+
+Anchored records, with the JS verifier and the public RPC (needs only Node):
+
+```bash
+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`:
+
+```python
+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](demo/base/mint-batch.sh), and every step's output is in [demo/base/](demo/base/). Each card's on-chain `contentHash` matches its pinned metadata.
+
+| Token | Name | Mint | Freeze |
+|---|---|---|---|
+| [1](https://basescan.org/nft/0xCAa3573b5550870A5e15C47c650b8700D70a8fA7/1) | Azure Knight | [tx](https://basescan.org/tx/0x595626d4645f5e067b8e1bd7c8b67cc2ea12c8051a5fb1846784659110496c30) | [tx](https://basescan.org/tx/0x39089c0f17410e044a407f0b9cf7d9125d5ecde71400200702e25df0669f6e50) |
+| [2](https://basescan.org/nft/0xCAa3573b5550870A5e15C47c650b8700D70a8fA7/2) | Emerald Wizard | [tx](https://basescan.org/tx/0x15a60342852c7f40f7ea283a55637195f102b69899bb82a2ff638f1130808bc8) | [tx](https://basescan.org/tx/0x52ead3396a533c8232ecab5540d61f9c3ef3d0bcbbf7b816aad1790088683b28) |
+| [3](https://basescan.org/nft/0xCAa3573b5550870A5e15C47c650b8700D70a8fA7/3) | Steel Cyborg | [tx](https://basescan.org/tx/0xfed072d1830d14c14bf4c60b912c079873e36cdfafc5bdb6cc6640e5b91d2a3e) | [tx](https://basescan.org/tx/0xa783b4aa35d4f382f1d19b21cb46377b70c83cb5a3a6c31f240d991e39935991) |
+| [4](https://basescan.org/nft/0xCAa3573b5550870A5e15C47c650b8700D70a8fA7/4) | Silver Huntress | [tx](https://basescan.org/tx/0xef0aecf8187f30aaa919f3fc48db4dfdd8a34aeb64485851c4ffff09d79a94ae) | [tx](https://basescan.org/tx/0x69af3f6c0ff486aae3f3aa2e63602e22e2c268382becec430a7eecaf7ea6c155) |
+| [5](https://basescan.org/nft/0xCAa3573b5550870A5e15C47c650b8700D70a8fA7/5) | Crimson Orc | [tx](https://basescan.org/tx/0xd3e4dde31bdec93d97d8ed469028eaddd1c98d8e1a33f40b6517cc3e04170858) | [tx](https://basescan.org/tx/0xc8c1b77f81b5b9338a37836d6905e60bb665b06b6d61c61bf4f75237d761ab16) |
+| [6](https://basescan.org/nft/0xCAa3573b5550870A5e15C47c650b8700D70a8fA7/6) | Golden Priest | [tx](https://basescan.org/tx/0x9c7d71c1e30d34eef8ba3e149800d70c7d44f5705127e69e5e81c6ea33d6b192) | [tx](https://basescan.org/tx/0x437f03b5ad49bab8b6505a02179277bce97b395c959518b1c801c923238c0008) |
+
+The collection is also on [OpenSea](https://opensea.io/collection/argus-mint-card). The same `contentHash` check as above works with `chain.connect("base")`.
+
+## License
+
+MIT

argus_mint-0.1.0/pyproject.toml

@@ -0,0 +1,100 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "argus-mint"
+dynamic = ["version"]
+description = "Provenance tokens for game assets: render from reviewed templates, pin to IPFS, mint ERC-721 cards and soulbound deeds, and anchor commitments and Merkle roots on-chain"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "smk762" }]
+keywords = [
+    "nft",
+    "erc-721",
+    "erc-5192",
+    "soulbound",
+    "eip-712",
+    "siwe",
+    "eip-4361",
+    "merkle-tree",
+    "commit-reveal",
+    "provenance",
+    "ipfs",
+    "foundry",
+    "solidity",
+    "ethereum",
+    "game-assets",
+    "generative-ai",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Framework :: Pydantic :: 2",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security :: Cryptography",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+# Base install is pure Python (no web3): templates, metadata, Merkle, vouchers, SIWE,
+# and the render/pin clients. web3 is only pulled by the `chain` extra.
+dependencies = [
+    "pydantic>=2.7",
+    "structlog>=24.0",
+    "pyyaml>=6.0",
+    "eth-account>=0.13",
+    "eth-abi>=5.0",
+    "eth-utils>=5.0",
+    "pycryptodome>=3.20",
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+chain = ["web3>=7.0"]
+cli = ["typer>=0.12", "rich>=13.0"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "ruff==0.15.16"]
+
+[project.scripts]
+argus-mint = "argus_mint.cli:app"
+
+[project.urls]
+Repository = "https://github.com/smk762/argus-mint"
+Homepage = "https://github.com/smk762/argus-mint#readme"
+Issues = "https://github.com/smk762/argus-mint/issues"
+Changelog = "https://github.com/smk762/argus-mint/blob/main/CHANGELOG.md"
+"Argus suite" = "https://github.com/smk762?tab=repositories&q=argus"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/argus_mint/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/argus_mint"]
+
+[tool.hatch.build.targets.sdist]
+# Python source only: the Foundry project (and its submodules) and the JS verifier
+# are not part of the pip package. The ABIs it needs live in src/argus_mint/abi.
+include = ["/src", "/tests", "/README.md", "/CHANGELOG.md", "/LICENSE", "/pyproject.toml"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+filterwarnings = ["ignore::DeprecationWarning"]
+markers = ["anvil: starts a local anvil node (skips without Foundry unless ARGUS_MINT_REQUIRE_ANVIL=1)"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+extend-exclude = ["src/argus_mint/_version.py"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM"]
+ignore = ["E501", "B008"]

argus_mint-0.1.0/src/argus_mint/__init__.py

@@ -0,0 +1,20 @@
+"""argus-mint — provenance tokens for game assets.
+
+Render from reviewed templates, pin to IPFS, mint ERC-721 cards and soulbound deeds,
+and anchor commitments and Merkle roots on-chain. No game logic lives here.
+"""
+
+from __future__ import annotations
+
+try:
+    # Written by hatch-vcs at build time (see pyproject [tool.hatch.build.hooks.vcs]).
+    from argus_mint._version import __version__
+except ImportError:  # running from a source checkout that hasn't been built
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        __version__ = version("argus-mint")
+    except PackageNotFoundError:
+        __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

argus_mint-0.1.0/src/argus_mint/__main__.py

@@ -0,0 +1,5 @@
+"""`python -m argus_mint ...` — same app as the `argus-mint` console script."""
+
+from argus_mint.cli import app
+
+app()

argus_mint-0.1.0/src/argus_mint/_codec.py

@@ -0,0 +1,63 @@
+"""Shared encoding helpers: keccak256, canonical JSON, and Pydantic field types for
+32-byte values and addresses. Pure; no I/O."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated, Any
+
+from Crypto.Hash import keccak as _keccak
+from eth_utils import is_address, to_checksum_address
+from pydantic import BeforeValidator, PlainSerializer
+
+
+def keccak256(data: bytes) -> bytes:
+    """Ethereum's keccak256 (not NIST SHA3-256)."""
+    return _keccak.new(digest_bits=256, data=data).digest()
+
+
+def canonical(doc: Any) -> bytes:
+    """Canonical JSON: sorted keys, compact separators, UTF-8, no NaN/Infinity.
+
+    The same document always gives the same bytes, so its hash is stable.
+    """
+    return json.dumps(doc, sort_keys=True, separators=(",", ":"), ensure_ascii=False, allow_nan=False).encode("utf-8")
+
+
+def to_bytes32(value: Any) -> bytes:
+    """Accept 32 raw bytes or a 0x-prefixed 64-hex-digit string."""
+    if isinstance(value, bytes | bytearray):
+        b = bytes(value)
+    elif isinstance(value, str):
+        if not value.startswith("0x") or len(value) != 66:
+            raise ValueError("expected 0x followed by 64 hex digits")
+        try:
+            b = bytes.fromhex(value[2:])
+        except ValueError as e:
+            raise ValueError("expected 0x followed by 64 hex digits") from e
+    else:
+        raise ValueError("expected 32 bytes or a 0x hex string")
+    if len(b) != 32:
+        raise ValueError(f"expected 32 bytes, got {len(b)}")
+    return b
+
+
+def hex0x(b: bytes) -> str:
+    return "0x" + b.hex()
+
+
+def to_address(value: Any) -> str:
+    """Validate an address and return its EIP-55 checksum form.
+
+    A mixed-case address with a wrong checksum is rejected (it's probably a typo).
+    """
+    if not isinstance(value, str) or not is_address(value):
+        raise ValueError(f"not a valid address: {value!r}")
+    return to_checksum_address(value)
+
+
+Bytes32 = Annotated[bytes, BeforeValidator(to_bytes32), PlainSerializer(hex0x, return_type=str, when_used="json")]
+Address = Annotated[str, BeforeValidator(to_address)]
+
+UINT64_MAX = 2**64 - 1
+UINT256_MAX = 2**256 - 1

argus_mint-0.1.0/src/argus_mint/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None