# Vaultfire Codex

**Complete line-by-line technical reference for every Solidity contract in the Vaultfire system.**

Generated: 2026-05-04 UTC
Builder: ghostkey.base.eth (`0xfA15Ee28939B222B0448261A22156070f0A7813C`)
License: MIT
No token. No VC. Solo-built.

---

## Purpose

This document is a complete rebuild blueprint. If every other file in the world disappeared, the contents of this Codex are sufficient — line-by-line — to reconstruct the entire Vaultfire smart contract system from zero.

It documents **209 Solidity files** across the workspace, deduplicated to **177 unique contracts** by SHA256 content hash, organized into 8 logical batches.

---

## Live on Base mainnet (chain 8453)

| Contract | Address | Status |
|---|---|---|
| **Vaultfire Genesis NFT** (1/1) | [`0xdC5fE0da17864608eDC3c24A675E6C4C24a9832C`](https://basescan.org/address/0xdC5fE0da17864608eDC3c24A675E6C4C24a9832C) | Token #1 minted to ghostkey |
| **Vaultfire Founders Edition** (5 max) | [`0x1bcD9B7Cad06D2BbC7FdedC46B32eFd1988e28cE`](https://basescan.org/address/0x1bcD9B7Cad06D2BbC7FdedC46B32eFd1988e28cE) | Open for public mint at 0.1 ETH |

Both deployed via Arachnid CREATE2 factory `0x4e59b44847b379578588920ca78fbf26c0b4956c`.

Compiler: solc 0.8.25, optimizer 200 runs, via-ir, evm cancun.

CREATE2 salts:
- Genesis: `0x7661756c74666972652d67656e657369732d3230323600000000000000000000` (= "vaultfire-genesis-2026")
- Founders: `0x7661756c74666972652d666f756e646572732d32303236000000000000000000` (= "vaultfire-founders-2026")

---

## Index

| # | Document | Contracts | Size | What it covers |
|---|---|---|---|---|
| 01 | [`01_LIVE_NFT.md`](./01_LIVE_NFT.md) | 3 | 83 KB · 1,724 lines | Live mainnet NFTs — Genesis 1/1, Founders Edition (5 max), deploy script. Full math for royalty (EIP-2981), price wei↔ETH, CREATE2 derivation, complete Foundry rebuild recipe. |
| 02 | [`02_V3_BONDS.md`](./02_V3_BONDS.md) | 25 | 132 KB · 2,349 lines | Audited V3 economic core — AIAccountabilityBonds, AIPartnershipBonds, BaseDignityBond, BaseYieldPoolBond, BondInsurancePool, BIPVault, PartnershipBondsEnhanced. All version snapshots (V2/V3.1/V3.3) with audit-finding cross-reference. |
| 03 | [`03_ERC8004.md`](./03_ERC8004.md) | 20 | 230 KB · 4,178 lines | ERC-8004 AI Agent Identity Standard — Identity / Reputation / Validation registries (V1, V3, V3.3), Adapter (with HIGH-14 timelock and HIGH-17 revocation patches), three-phase EMA, Bayesian prior, slash math. |
| 04 | [`04_BELIEF_ORACLE.md`](./04_BELIEF_ORACLE.md) | 40 | 159 KB · 3,411 lines | ZK proof verification, oracle aggregation, quantum-resistant Dilithium attestor, Belief verifiers (V2/V3 with epoch-aware mapping), MultiOracleConsensus (commit-reveal + slash pool), FlourishingMetricsOracle (TWAP EMA), BaseOracle, TrustOracle. |
| 05 | [`05_KEYPROTOCOL.md`](./05_KEYPROTOCOL.md) | 17 | 109 KB · 1,941 lines | VaultfireKeyProtocol — agent vaults (KeyVault), session keys, scoped delegation, SLA enforcer, insurance pool, safety manager, compliance registry, reputation decay, Factory, mocks. The "agent acts as user" trust layer. |
| 06 | [`06_GOVERNANCE_MISC.md`](./06_GOVERNANCE_MISC.md) | 26 | 127 KB · 2,403 lines | Multisig governance (5 variants with audit deltas), AntiSurveillance, PrivacyGuarantees, MissionEnforcement, TaskEscrow, DisputeResolution, CapabilityCredentials, ReputationStaking, ForumRegistry, libraries, deploy scripts. |
| 07 | [`07_SPRINTS_TELEPORTER_VNS.md`](./07_SPRINTS_TELEPORTER_VNS.md) | 13 | 116 KB · 1,919 lines | Sprint contracts — ERC-4626 BIPVault, ERC-5192 StreetCred soulbound, EIP-7702 BatchOnboarder. Plus Avalanche Teleporter cross-chain bridge (V1 + V3.3 with CRIT-02 ECDSA fix), VNS, StreamNFT. |
| 08 | [`08_DEPRECATED_ARCHIVE.md`](./08_DEPRECATED_ARCHIVE.md) | 33 | 215 KB · 5,650 lines | Historical archive — every deprecated contract documented anyway. V1 bonds, FreedomVow, CovenantFlame, GhostkeyAttribution, RewardStream variants, etc. With "why it didn't make production" inference for each. |
| **Total** | | **177 unique** | **~1.2 MB** | **~25,000 lines of explanation** |

(Plus `MANIFEST.txt` — full list of file paths in each batch.)

---

## How to use this Codex

**To rebuild from zero:**
1. Start with `01_LIVE_NFT.md` — the contracts that are actually live on-chain right now. Use the rebuild recipe at the bottom.
2. For the full V3 production stack, follow `02_V3_BONDS.md` deployment order section, then `03_ERC8004.md` deployment order, then `06_GOVERNANCE_MISC.md` for governance.
3. `05_KEYPROTOCOL.md` is the trust layer — depends on identity/reputation registries from `03_ERC8004.md`.
4. `04_BELIEF_ORACLE.md` covers the verification primitives that the bonds depend on.
5. `07_SPRINTS_TELEPORTER_VNS.md` adds cross-chain and naming.
6. `08_DEPRECATED_ARCHIVE.md` is reference-only — do NOT redeploy these.

**To understand a specific contract:**
- Find it in the manifest, jump to its document, read the line-by-line walkthrough + math + invariants.

**To verify on-chain behavior matches source:**
- Each live contract document includes the constructor args used, exact compiler flags, and `cast call` verification commands.

---

## Math reference shortcuts

| Topic | Document | Section |
|---|---|---|
| EIP-2981 royalty calculation | 01 | Math section, Founders Edition |
| Wei ↔ ETH conversion | 01 | Math section |
| CREATE2 address derivation | 01 | Rebuild Recipe |
| Bond escrow / slashing math | 02 | Per-contract Math sections |
| Three-phase EMA reputation | 03 | Global Math Reference |
| Bayesian prior on reputation | 03 | Global Math Reference |
| Belief resonance scoring | 04 | Math formulas section |
| TWAP weighted aggregation | 04 | FlourishingMetrics V3 |
| ECDSA digest binding | 04 | Dilithium V3 |
| Reputation decay over time | 05 | Math Reference |
| SLA penalty curve | 05 | Math Reference |
| Insurance premium pricing | 05 | Math Reference |
| Multisig quorum thresholds | 06 | Per-variant tables |
| ERC-4626 share/asset conversion | 07 | BIPVault section |
| StreetCred 5-component score | 07 | Sprint-5192 section |
| StreamNFT linear vesting | 07 | StreamNFT section |

---

## Audit history (referenced throughout)

The V3.3 production stack incorporates fixes for these audit findings:

- **CRITICAL** (10): CRIT-01 through CRIT-10 — covering multisig replay, balance-delta accounting, ECDSA bridge auth, CEI ordering, fee-on-transfer, recipient binding, cooldown enforcement, etc.
- **HIGH** (21): HIGH-01 through HIGH-21 — including bonus state ordering, identity checks, two-step guardian, timelock enforcement, revocation paths, bridge notification, etc.
- **MEDIUM/LOW**: documented in individual contract sections.

Full mapping in `02_V3_BONDS.md` Section 25 (cross-contract reference), `03_ERC8004.md` audit history section, and `06_GOVERNANCE_MISC.md` MultisigGovernance variants.

---

## Verification

Every contract address, every salt, every line count, every byte count in this Codex was generated from the actual files in the workspace at the time of writing — not from memory.

This Codex is the canonical record. If anything in the future contradicts it, this document is the source of truth for what was deployed and why.

— ghostkey316, 2026-05-04
