# Vaultfire V3 — Base Pilot Config

## Scope of the pilot
- Chain: **Base only** (chainId 8453).
- Users: allowlisted only. No public V3 write access.
- Duration: 4 weeks minimum, extendable.
- Existing V2 addresses across Base/Avalanche/Arbitrum/Polygon: **unchanged**.
- This is a prepared, review-only configuration—not a deployment, activation,
  production-readiness, partner-acceptance, or mainnet-approval claim.
- The capped pilot is limited to **exactly one active, explicitly allowlisted
  design partner** when (and only when) all activation gates are met. The
  checked-in review manifest has zero active partners. The controller enforces
  a maximum of one active design partner; the manifest, governance proposal,
  and independent post-state review must additionally prove the intended
  partner address and activation state.
- Solana and every cross-chain value flow are excluded from this Base-only
  pilot. They are unfinished/out of scope and cannot be enabled, represented
  as settled, or inferred from this configuration.

## Privacy, disputes, and flourishing measurements

“Privacy-preserving” in this pilot means **data minimization and carefully
reviewed commitments/references**, not hidden, private, anonymous, or erasable
transactions. Base transactions, calldata, events, addresses, and published
commitments remain public and durable. Do not place PII, secrets, raw evidence,
or freeform narratives on Base; a hash/commitment can still be linkable and is
not automatically anonymous.

Any amount supplied to `DisputeRegistryV3` with a filing is a **fully refundable
filing bond**. It is not a protocol fee, adjudicator fee, penalty, slash,
forfeiture, reward contribution, or treasury transfer. The registry credits
the recorded filing bond back to the challenger exactly once when the dispute
is finalized upheld or rejected, including timeout rejection. No minimum filing
amount is configured in this review-only pilot.

Flourishing measurements, if separately collected under an approved policy,
are non-slashable and cannot authorize confiscation or a distribution. They are
separate from objective-breach evidence and from the pilot's bond economics.
The initial pilot rejects bond-linked flourishing reward terms and has no
flourishing-weighted reward or principal-distribution behavior.

## Bond reward and settlement semantics (initial pilot)

The Base pilot has **no bond-linked reward behavior**. Deploy every
`PartnershipBondV3Safe` with `rewardProgram=address(0)`, and require every
partnership/accountability terms payload to use
`flourishReward*Hash=bytes32(0)` and `rewardProgramId=0`. These fields remain
in the typed-term ABI for compatibility, but nonzero values are rejected before
any signatures can create a bond. Do not publish or sign a reward-program
address, reward ID, or flourishing-reward hash for a pilot bond.

The similarly historical `partnershipShareBps` settlement input is not a
protocol, treasury, owner, or reward-program share. Pilot settlement requires
it to equal zero. All funded partnership principal is credited to party A and
party B according to their signed/attested split; rounding remainder is
credited to party B. The bond owner, governance treasury, and
`RewardProgramV3` receive no partnership principal.

`RewardProgramV3` is outside the final Base-mainnet bonds-only manifest and
must not be deployed or funded through this release path. Any future
reward-enabled bond release needs a separate audited version, explicit scope,
and explicit approval; it must not be enabled through a configuration-only
change.

## Canonical typed manifest (source of truth before approval)

`base_v3_deployment_manifest.json` is the machine-readable review artifact for
this pilot. It records Base chain ID `8453`, the canonical Base USDC address
and six decimals, human display amounts, and exact decimal atomic integers.
The controller is native-ETH-denominated in the canonical manifest: its global
cap is **0.40 ETH** = `400000000000000000` wei and its per-position cap is
**0.20 ETH** = `200000000000000000` wei. These are not USDC values and must
never be described as generic “base units.” The checked-in review manifest
keeps every V3 deployment address unset and cannot produce a production payload.

Validate it offline with:

```bash
python3 pr8/pilot/deployment_manifest.py
```

The stricter `--for-payload` mode is intentionally fail-closed until the five
signers, separate guardian, treasury, attesters, adjudicators, design partners,
audit evidence, explicit approval, and verified V3 addresses are all supplied.
It does not sign, deploy, write, or broadcast anything.

## On-chain pilot controller (required)

`BasePilotAccessControllerV3` is a separate, composable controller deployed
only on Base. It holds no assets and is not an owner, escrow, or withdrawal
path. Factories/modules that participate in the pilot must opt into it:

1. the governance-owned factory/module calls `registerPosition(partner,
   position, initialAllocation)` after creating a position and before it
   accepts the pilot allocation;
2. it calls `increasePositionAllocation(position, amount)` before accepting
   additional value; and
3. it calls `releasePositionAllocation(position, amount)` after a redemption,
   withdrawal, or settlement reduces the accounted pilot value.

The controller is constructed with `governance=<MultisigGovernanceV3>`, checks
`block.chainid == 8453`, and defaults to **both** `deployEnabled=false` and
`writeEnabled=false`. Only the governance contract can allow design partners,
allow modules, set caps, or enable either switch. No EOA configuration path
exists.

Withdrawal code must never use a controller approval as a precondition for a
withdrawal. In particular, do not call an allocation increase in a withdrawal
flow; a best-effort/post-withdrawal allocation release is permissible. The
controller's release hook itself remains enabled when deploys and writes are
disabled, but asset and bond withdrawal rights are deliberately outside this
controller.

## Controller caps

The controller tracks generic base-unit allocation. The global cap is the sum
of allocations registered through the controller; the per-position cap is
snapshotted when a position is registered and bounds that position for its
life. A later governance cap change applies to subsequently registered
positions and never weakens an already registered position's limit. These are
supplementary pilot limits, not a replacement for the contract-specific limits
below.

| Controller value | Initial Base pilot setting | Enforcement |
|---|---:|---|
| `maxGlobalCap` | 0.40 ETH = `400000000000000000` wei | immutable constructor ceiling for `globalCap` |
| `maxPerPositionCap` | 0.20 ETH = `200000000000000000` wei | immutable constructor ceiling for `perPositionCap` |
| `globalCap` | 0.40 ETH = `400000000000000000` wei initially | `totalAllocated + amount <= globalCap <= maxGlobalCap` |
| `perPositionCap` | 0.20 ETH = `200000000000000000` wei initially | `positionAllocated + amount <= positionCap <= maxPerPositionCap` |
| Design partners | exactly one active partner when activated; otherwise none | one explicitly named governance allowlist entry required at position registration and write |
| Factories/modules | named, governance allowlist | required to call controller hooks |
| `deployEnabled` | `false` | required to register a position |
| `writeEnabled` | `false` | required to increase a position allocation |

The initial values above must be encoded in a single-purpose governance
proposal using the manifest's exact native-wei integers. Governance can
temporarily lower either configured cap, but cannot raise it above the
constructor-pinned maximum. They are not evidence that a deployment has
occurred. Because the controller's allocation is an
untyped `uint256`, a participating module must be verified to account for
native ETH consistently; it must not substitute USDC or another asset.

## Contract-specific caps (deployment configuration)

| Contract | Cap |
|---|---|
| PartnershipBondV3Safe | owner-selected immutable native-wei per-party, per-bond, and aggregate caps |
| AccountabilityBondV3Safe | owner-selected immutable native-wei per-bond and aggregate caps |

`RewardProgramV3`, `TaskEscrowV3`, `MutualAidPoolV3`, `VaultfireBIPVaultV3`,
validation/reputation modules, and mandate modules are outside the final
bonds-only Base manifest: they have no deployment entry, cap, route, owner, or
value flow in this release path.

The review manifest binds the owner-selected tiny pilot profile: partnership
`0.01 ETH` per party, `0.02 ETH` per bond, and `0.20 ETH` aggregate;
accountability `0.02 ETH` per bond and `0.20 ETH` aggregate. These are exact
immutable constructor caps, not UI limits. A production payload remains blocked
until governance and operating-role addresses, independent audit evidence,
verified deployment addresses, and explicit deployment approval are supplied.
Bond capacity is released only when principal is actually withdrawn from the
pull-payment ledger, not when settlement/refund creates the credit. The
controller caps above remain supplemental and never replace these contract-level
constraints.

## Multisig configuration
- Threshold: 3-of-5.
- Signers: (to be finalized before enable).
- Timelock: 24h for admin calls and the immutable nonzero floor.
- Guardian: separate hot key, pause-only, and never a signer.
- Guardian rotation: a timelocked multisig proposal names a pending guardian;
  the pending key must accept after the configured cooldown. It cannot gain
  authority before acceptance.
- Guardian pause targets: deployment-time targets plus append-only targets added only by a 3-of-5 timelocked self-call. The guardian may call only `pause()` on those targets; it cannot unpause, execute, reconfigure, move funds, or change signers.

## Enable checklist (must ALL be green before flipping V3 writes on)
- [ ] Audit engaged, no unmitigated High findings.
- [ ] 15 invariants passing under fuzzing on Base fork.
- [ ] `x402-registry.contract.spec.ts` green in CI.
- [ ] ERC-4626 property tests green.
- [ ] Selector-scan clean on all V3 deploys.
- [ ] Monitoring signals producing alerts on staging.
- [ ] Incident runbook rehearsed with all signers.
- [ ] Public status page + banner mode functional.
- [ ] Built migration UI reviewed and deployed at `/migrate`.
- [ ] `x402` payee address moved off deployer to multisig treasury.
- [ ] Two on-call engineers scheduled.
- [ ] Bug bounty enabled.
- [ ] `BasePilotAccessControllerV3` deployed on Base with the multisig as
  immutable governance; chain ID, bytecode, and constructor arguments verified.
- [ ] Governance proposals recorded for the design-partner allowlist, approved
  factory/module allowlist, exact one-partner limit, native-ETH global/per-position
  caps, and the two enable flags.
- [ ] Controller hooks exercised against the actual participating
  factory/module: rejected when disabled, rejected above caps, accepted for
  approved partners, and do not impede a withdrawal.
- [ ] Written acceptance, minimal-data terms, permitted module/route, exit
  path, and no-governance-role confirmation are independently recorded for the
  one proposed design partner.
- [ ] Qualified counsel has approved or otherwise cleared the launch-specific
  terms/disclosures; a Base Sepolia rehearsal is complete; and any x402
  settlement claim has its own real evidence pack. Checked-in placeholders for
  these gates remain non-passing.
- [ ] `pilot_gate_evidence.json` contains real command/deployment/audit/
  monitoring evidence hashes; the gate checker reports `pilotReady: true`.

## Rollback triggers
Any of these = immediate guardian pause + write halt:
- Invariant #1 (assets ≥ liabilities) broken on any V3 contract.
- Invariant #6 (payouts ≤ collateral + rewards) broken.
- Any P0 finding from audit.
- Any confirmed key compromise.
- Any Base RPC + fallback both failing simultaneously for > 15 minutes.
