# Vaultfire V3 Source Tree

**Public candidate:** current GitLawb `main` HEAD; run
`../scripts/verify-v3-source.sh` to print and verify its exact commit and tree  
**Status:** native-tested source candidate; not deployed, activated, or
partner-authorized  
**Rule:** V2 remains the live default. V3 is additive. Tests and CI must not send
live transactions.

Read [the public V3 status page](../V3_STATUS.md) before evaluating or using
this tree. It records the exact candidate, audit scope, test results, unsupported
claims, and remaining technical and human gates.

## Layout

```
contracts/          # V3 Solidity sources
test/
  invariants/       # stateful and bounded safety invariants
  fork/             # V2-preservation and fork-test surfaces
lib/                # pinned Foundry dependencies
script/             # deployment/bootstrap scripts; authorization remains gated
foundry.toml        # via_ir=true, optimizer on
```

## Required native build

```
git submodule update --init --recursive
forge build
```

## Test

```
forge test -vv                             # run the full V3 Solidity test suite
forge test --match-contract Inv03          # single invariant
BASE_RPC_URL=... forge test --match-path test/fork/base/**   # V2 preservation forks
```

## Native release criteria

- `forge build` must succeed under `--via-ir`.
- `forge test` must exercise the concrete local deployment fixtures.
- Fork/RPC checks must run separately against an approved endpoint without
  sending live transactions.

The current Base source was compiled with Foundry Forge 1.7.1 and Solidity
0.8.24 using this tree's pinned dependencies and `foundry.toml` settings.
All 31 deployable runtimes were measured below the 22,528-byte project ceiling;
the largest was `AccountabilityBondV3Safe` at 22,460 bytes. The complete
non-fork suite passed 246 of 246 tests in isolated shards. Fork/RPC execution,
deployed-bytecode verification, and deployment authorization remain separate
open gates.

## Initial-pilot reward semantics

Partnership and accountability bonds are **principal-only** for the Base
initial pilot. Their signed terms retain the legacy reward fields for ABI and
typed-data compatibility, but creation rejects every nonzero
`flourishReward*Hash` and `rewardProgramId`; a partnership deployment also
rejects a nonzero reward-program address. `RewardProgramV3` remains a separate
pre-funded reward module, but it is not connected to bond settlement in this
pilot.

Partnership settlement requires `partnershipShareBps == 0`. The complete
funded principal is credited only to party A and party B; any rounding
remainder goes to party B, never to the bond owner, treasury, or a reward
program. Do not describe the former `partnershipShareBps` field as a treasury,
protocol, or flourishing reward share.

## Publication and deployment boundary

The exact source candidate is public on GitLawb `main`. Publication does not
authorize a deployment, activation, partner pilot, wallet action, governance
action, or live transaction.

Before any deployment, rerun the complete Base toolchain, runtime-size,
reproducibility, static-analysis, fork/RPC, and live address/runtime checks.
Solana additionally requires reproducible SBF builds, native Rust/Anchor tests,
local-validator execution, program-ID and upgrade-authority verification, and
mainnet evidence. Operations, legal, privacy, partner, and human-authorization
gates must also close.

## Settlement challenge remedy

`DisputeRegistryV3.fileDispute` now accepts a bond dispute only while the bond is
in `SettlementRequested`. At filing, the registry records the subject-provided
settlement snapshot, settlement-request time, challenge deadline, and filing
time. `PartnershipBondV3Safe` and `AccountabilityBondV3Safe` accept an upheld
dispute only when all of that settlement-attempt provenance matches the current
request; the registry ABI is therefore `isFinalizedUpheldForSettlement(...)`,
not the former subject-only upheld check.

After the signed challenge window, `resolveChallenge` is permissionless and
remains callable while paused. It is terminal and one-shot: it changes
`Challenged` to `Cancelled`, never to `Finalizable`. The bonds create native
pull-payment credits without reducing `nativeLiability` or the Base pilot
controller allocation until the original principal owner withdraws:

- Partnership: each party receives exactly its own funded principal.
- Accountability: the company receives its funded principal; the counterparty
  receives no contested slash payout.

`SettlementChallengeBoundV3` records the bound dispute provenance, and
`ChallengedSettlementCancelledV3` records the terminal cancellation/refund
path. Integrators must update `IDisputeSubjectV3` implementations to expose
`settlementChallengeContext` and update registry callers to use the new
settlement-bound upheld check.
