chore: initial public release (v1.0.0)

T3 Programmable Fiat Framework — an EIP-2535 Diamond ERC-20 deposit token with
programmable transfer envelopes and per-bank claim attribution, targeting a
permissioned Hyperledger Besu consortium.

This repository is a published snapshot, not the development repository. Each
release is a single commit containing the full tree at that version. See the
"Releases and repository model" section of README.md for why.

Licensed under Apache-2.0. Not production-audited; see NOTICE, REGULATORY-STATUS.md
and KNOWN-ISSUES.md for scope, open legal/compliance questions, and known limitations.

Author: jessedh

.env.example

@@ -0,0 +1,60 @@
+# =============================================================================
+# T3 Programmable Fiat Framework — root environment example
+# Copy to `.env` and fill in. For local development you can run entirely against
+# a local chain; no real keys or testnet access are required.
+# Per-service examples also exist: indexer/.env.example, ui-management/.env.example
+# =============================================================================
+
+# =============================================================================
+# Core Addresses (populated after you deploy locally)
+# =============================================================================
+DIAMOND_ADDRESS=0xYOUR_DIAMOND_ADDRESS
+FORWARDER_ADDRESS=0xYOUR_FORWARDER_ADDRESS
+TARGET_ADDRESS=0xYOUR_DEFAULT_TARGET_ADDRESS
+RECIPIENT_ADDRESS=0xYOUR_DEFAULT_RECIPIENT_ADDRESS
+
+# =============================================================================
+# Local chain (Hardhat node or local Besu devnet)
+# =============================================================================
+RPC_URL=http://127.0.0.1:8545
+NETWORK_LABEL=localhost
+
+# Local Besu devnet (used by the `besu-local` Hardhat network).
+BESU_LOCAL_RPC_URL=http://127.0.0.1:8545
+# LOCAL-DEV-ONLY: the well-known public Hardhat account #0 key is used by default
+# (prefunded in the local Besu genesis). Only set this when targeting a real node.
+# BESU_LOCAL_PRIVATE_KEY=0xYOUR_LOCAL_DEPLOYER_KEY
+
+# Solidity build overrides (optional)
+# OPT_RUNS=100
+# VIA_IR=true
+# EVM_VERSION=paris
+
+# =============================================================================
+# Relayer (ERC-2771 meta-transaction forwarder)
+# =============================================================================
+RELAYER_PRIVATE_KEY=0xYOUR_RELAYER_PRIVATE_KEY
+ALLOWED_TO=0xYOUR_DIAMOND_ADDRESS
+ALLOWED_SELECTORS=0xa9059cbb
+MAX_GAS=1500000
+MAX_TTL_SECONDS=1209600
+RATE_WINDOW_MS=60000
+RATE_LIMIT=1000
+OBSERVATION_MODE=false
+ENFORCE_WARN_AT=1000
+ENFORCE_DENY_AT=1000
+PORT=8080
+
+# =============================================================================
+# UI (Next.js) — see ui-management/.env.example for the full list
+# =============================================================================
+NEXT_PUBLIC_LOCAL_DIAMOND_ADDRESS=0xYOUR_DIAMOND_ADDRESS
+NEXT_PUBLIC_LOCAL_FORWARDER_ADDRESS=0xYOUR_FORWARDER_ADDRESS
+NEXT_PUBLIC_PONDER_URL=http://localhost:42070/
+NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=YOUR_PROJECT_ID
+
+# =============================================================================
+# Indexer (Ponder) — see indexer/.env.example for the full list
+# =============================================================================
+PONDER_RPC_URL=http://127.0.0.1:8545
+PONDER_DIAMOND_ADDRESS=0xYOUR_DIAMOND_ADDRESS

.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  contracts:
+    name: Contracts (compile, test, gates)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: "npm"
+      - name: Install
+        run: npm ci
+      - name: Compile
+        run: npm run compile
+      - name: Test
+        run: npm test
+      - name: Selector collision check
+        run: node scripts/selector-collision-check.js
+      - name: Manifest ↔ ABI parity
+        run: node scripts/check-manifest-abi-parity.js
+      - name: Storage layout gate
+        run: node scripts/check-storage-layout.js
+      - name: Contract size gate
+        run: node scripts/check-contract-size.js
+      - name: Doc-claim gate (references in shipping STATUS docs must resolve)
+        run: node scripts/check-doc-claims.js
+
+  secrets:
+    name: Secret scan (gitleaks)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read   # gitleaks-action lists PR commits via the API to scope the scan
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: gitleaks
+        uses: gitleaks/gitleaks-action@v2
+        env:
+          # gitleaks-action v2 requires GITHUB_TOKEN to scan pull_request events.
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITLEAKS_CONFIG: .gitleaks.toml
+          # No PR comments (avoids needing pull-requests: write); the run status is enough.
+          GITLEAKS_ENABLE_COMMENTS: "false"

.gitignore

@@ -0,0 +1,74 @@
+# Environment files — CRITICAL: contains private keys and secrets
+.env
+.env.*
+!.env.example
+
+# Generated local Besu devnet keys/genesis
+.besu-local/
+
+# Build artifacts and cache
+/node_modules
+**/node_modules/
+/artifacts/*
+artifacts/*
+/cache
+/dist
+
+# Build output
+/ui-management/.next
+/ui-management/tsconfig.tsbuildinfo
+
+# Deployment tarballs — regenerable from source
+*.tar.gz
+
+# Coverage and test reports — regenerable
+coverage/
+coverage.json
+playwright-report/
+test-results/
+test/test-results/
+**/.last-run.json
+
+# Generated reports
+gasReport.md
+contract-size-report.txt
+reports/
+
+# Temporary files
+~$*
+*.exp
+*.tmp
+*.temp
+
+# macOS specific
+.DS_Store
+**/.DS_Store
+*/*.DS_Store
+
+# IDE files
+.vscode/settings.json
+.gemini/
+.auto-claude/
+.auto-claude-security.json
+.auto-claude-status
+.claude/settings.local.json
+.claude_settings.json
+.worktrees/
+.security-key
+logs/security/
+
+# Third-party agent/tool config stubs (not project source)
+.agent/
+.roo/
+.continue/
+.vivus/
+.wake/
+
+# Auth credentials
+gha-creds-*.json
+
+# NotebookLM extract (regenerated via scripts/export-notebooklm-docs.js)
+T3-NotebookLM-Sources/
+
+# Local deployment artifact (consumed by e2e relayer tests; regenerated on deploy)
+.forwarder_address

.gitleaks.toml

@@ -0,0 +1,70 @@
+# Gitleaks configuration — T3 Programmable Fiat Framework
+#
+# Extends the default ruleset and adds project-specific rules for credential
+# shapes the default rules do NOT match.
+#
+# POLICY: new secrets are remediated, never suppressed. The allowlist below
+# covers only values that are public by construction (EVM addresses, the
+# well-known Anvil test keys). There are no commit-SHA suppressions: this repo
+# publishes as a files-only snapshot with no git history, so there is no history
+# for a scanner to trip over.
+#
+# ⚠️ A CLEAN SCAN IS NECESSARY, NOT SUFFICIENT.
+# Gitleaks matches known secret SHAPES. On 2026-08-25 it reported "no leaks
+# found" against a tree that contained a live root SSH password twelve times —
+# once in a JSON-escaped tool-permission string, and eleven times inside expect
+# scripts (SEC-3). The `expect-send-credential` rule below exists because of
+# that miss. The default-deny promotion allowlist
+# (scripts/lib/public-allowlist.js), not this scanner, is the control that keeps
+# secrets out of the public snapshot.
+
+[extend]
+useDefault = true
+
+# --- Project-specific rules -------------------------------------------------
+
+[[rules]]
+id = "expect-send-credential"
+description = "expect(1) script sending a literal credential — the SEC-3 shape the default ruleset misses"
+# NOTE: Go/RE2 has no lookahead. Instead of excluding command words, we require
+# the sent literal to contain NO whitespace — shell commands sent by expect
+# ("cat /root/x", "pm2 logs") always contain a space; a password rarely does.
+# Requires BOTH a digit and a punctuation character somewhere in the literal.
+# Command words sent by expect ("pm2reload", "restartservices") have neither;
+# passwords almost always have both. RE2 has no lookahead, so this is expressed
+# as alternation over the two orderings rather than two assertions.
+regex = '''send\s+\\{0,2}"{1,3}(?:[^"\s]*[0-9][^"\s]*[!-/:-@\[-`{-~][^"\s]*|[^"\s]*[!-/:-@\[-`{-~][^"\s]*[0-9][^"\s]*)\\{1,2}r"'''
+tags = ["credential", "expect", "SEC-3"]
+
+[[rules]]
+id = "ssh-password-in-config"
+description = "plaintext password adjacent to an ssh/scp invocation in a config or tool-permission blob"
+# Value may contain spaces -- only the closing quote terminates it -- but must
+# LOOK like a credential: at least one digit and one punctuation character.
+# Without that, form-field declarations such as
+#   password: { label: "Password", type: "password" }
+# match, and a rule that flags UI labels trains people to ignore it.
+regex = '''(?i)(sshpass\s+-p|password)\s*[=:]?\s*\\{0,2}"{1,3}(?:[^"\n]*[0-9][^"\n]*[!-/:-@\[-`{-~][^"\n]*|[^"\n]*[!-/:-@\[-`{-~][^"\n]*[0-9][^"\n]*)"'''
+tags = ["credential", "ssh", "SEC-3"]
+
+[allowlist]
+description = "Values that are public by construction"
+
+# Internal planning docs. These never publish (hardDeny blocks `plans/` in
+# scripts/lib/public-allowlist.js) and they DESCRIBE credential patterns in
+# prose — e.g. documenting the expect-style `send "<literal>\r"` shape that the
+# expect-send-credential rule above detects. That self-reference is the only
+# reason this path is listed. It is NOT a licence to store secrets here.
+# Not anchored with ^ deliberately: gitleaks reports ABSOLUTE paths when
+# --source points outside the repo root (as the promotion staging scan does),
+# so an anchored pattern silently fails to match.
+paths = [
+  '''(^|/)plans/.*''',
+]
+
+# Regexes for values that look like secrets but are public.
+regexes = [
+  '''0x[0-9a-fA-F]{40}\b''',                                                # 20-byte EVM addresses (public on-chain data)
+  '''0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80''', # Anvil/Hardhat account #0 key — published in Foundry/Hardhat docs
+  '''0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d''', # Anvil/Hardhat account #1 key — same
+]

.npmrc

@@ -0,0 +1,4 @@
+# hardhat (2.x) and @nomicfoundation/hardhat-ignition (3.x) have a peer-dep
+# mismatch on hardhat's major; ignition is not used by the MVP. Enable
+# legacy-peer-deps so a plain `npm install` works for newcomers.
+legacy-peer-deps=true

.nvmrc

@@ -0,0 +1 @@
+22

CHANGELOG.md

@@ -0,0 +1,90 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] — 2026-08-25 — MVP foundation
+
+Initial public foundation of the T3 programmable fiat framework: an EIP-2535
+Diamond ERC-20 deposit token with programmable transfer envelopes and per-bank
+claim attribution, targeting a permissioned Hyperledger Besu consortium.
+
+> Note: this is a foundation release, not a production-audited deployment. It has
+> no production history. See the README for current scope and the planned waves.
+
+### Added
+- **Diamond core (EIP-2535):** proxy + DiamondCut/DiamondLoupe, manifest-driven
+  facet registration (`scripts/lib/facet-manifest.js`) as the single source of
+  truth for deploys, ABI generation, and the selector-collision / ABI-parity gates.
+- **ERC-20 deposit token:** base, pausable, direct transfer, mint/burn, fee logic,
+  admin facets with isolated diamond storage per module.
+- **Programmable envelopes:** create / finalize / reverse / dispute lifecycle with
+  configurable settlement type (CRYPTO_DIRECT, FIAT_INSTITUTIONAL) and expiration
+  behavior (immediate, half-life decay, hold-until-manual, oracle-conditional,
+  auto-reverse, dispute-hold). Includes SmartLock and envelope-inheritance facets.
+- **Per-bank claim attribution:** consortium mints route through
+  `IssuanceAccountingLib.mintAttributed`; envelope finalization routes through
+  `ClaimAttributionLib.finalizeEnvelopeClaims` + `substituteLiability` for
+  cross-institution settlement. Activated via `initializeClaimAttribution`
+  (requires zero supply at init).
+- **Consortium / banking:** multi-asset vault with factor-based collateral check
+  (default 100% = 1:1; per-bank factors configurable), institution lifecycle /
+  policy / registry, custodian registry, membership.
+- **Rules / compliance:** rules engine + config, automated emergency response
+  (role-gated, fail-closed).
+- **Wallet recovery** state machine and **relayer fallback** (4-hour
+  self-declaration) for ERC-2771 meta-transactions.
+- **Services:** Ponder event indexer, ERC-2771 meta-transaction relayer, and the
+  settlement keeper (ships DISABLED and triple-gated).
+
+### Changed
+- **Compliance arming observability (CF-R Obs-1):** the single `activeScopeCount`
+  was split into per-control counters (`sanctionsScopeCount`, `kycScopeCount`,
+  `cipScopeCount`, `travelRuleScopeCount`); `activeScopeCount()` remains as their
+  sum and `complianceArmed()` reports any-armed. The legacy getters changed
+  meaning: `isKycEnforceActive()` / `isCipEnforceActive()` /
+  `isTravelRuleEnforceActive()` now report only the **network-scope** policy
+  baseline, and `isScreeningEnforceActive()` reports whether any institution has
+  per-institution sanctions enforcement enabled. Off-chain consumers that need
+  "any scope armed" should migrate to the per-control `*ScopeCount()` views or
+  `complianceArmed()`.
+- **Policy relax guard (CF-R Obs-2):** lowering an enforcement-class policy
+  below its effective parent — including via `setNetworkPolicy` and via
+  `clearInstitutionPolicy` / `clearWalletPolicy` of a tighter override — now
+  requires `COMPLIANCE_EXEMPTION_ROLE` and emits `ComplianceExemptionGranted`.
+- **Escrow-creation recipient screening (K-F1):** `ESCROW_IN` compliance checks
+  now screen the named recipient (payee-resolved through recovery) in addition
+  to the sender. Cambio bearer notes (`to == address(0)`) remain exempt.
+- **Bulk recovery release gating (CF-2 core):** `applyBulkPolicy` ConfirmFiat
+  and `resolveCambioNotesBulk` cancel/expire releases now run the
+  `ESCROW_RELEASE` compliance gate against the resolved payee before value
+  moves. Envelope reverse/clawback refund legs are deliberately not gated yet —
+  they route to admin hold in the compliance-hold work (D2).
+- **Screening freshness enforcement (C-F9):** when sanctions are armed
+  (`sanctionsScopeCount > 0`) and an admin has set `screeningStaleAfter > 0`,
+  the sanctions precheck fails closed (`ComplianceScreeningStale`) for any
+  checked party whose network screening is stale — including never-screened
+  wallets (`lastScreenedAt == 0`), which is deliberately stricter than the
+  informational `isScreeningStale()` view. The default window of 0 preserves
+  prior behavior exactly.
+
+### Security & hygiene
+- Tier-0 remediations: restricted permissionless metric updates, role-gated
+  emergency deactivation, custody-takeover guard, recovery paths routed through
+  the issuer-domain escrow release overload, fail-closed emergency tests.
+- Apache-2.0 license; Solidity SPDX headers retained pending owner decision;
+  gitleaks configuration.
+
+### Implemented but not production-activated
+- Wave 4: single-bank attributed issuance capacity (quote / reserve / execute) —
+  `IssuanceControlFacet`, behind the `capacityModelActive` admin gate.
+- Wave 5: bilateral-net settlement cycle (open / propose / confirm / fund /
+  finalize / fail) with replay-protected funding attestation —
+  `SettlementCycleFacet`, behind the `settlementModelActive` admin gate.
+
+### Not yet implemented
+- Multilateral-net CCP settlement — the documented scale endgame, gated on a
+  future ADR and counsel review. ADR-003 covers the bilateral-net design that
+  shipped; multilateral is explicitly out of scope for this release.

CODE_OF_CONDUCT.md

@@ -0,0 +1,36 @@
+# Contributor Code of Conduct
+
+## Our pledge
+
+We as members, contributors, and maintainers pledge to make participation in our
+project a harassment-free experience for everyone, regardless of age, body size,
+visible or invisible disability, ethnicity, sex characteristics, gender identity
+and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment:
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes
+
+Examples of unacceptable behavior:
+- The use of sexualized language or imagery, and unwelcome sexual attention
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainers. All complaints will be reviewed and
+investigated promptly and fairly. Maintainers are obligated to respect the
+privacy and security of the reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1.