# Vaultfire V3 Open Compatibility Specification 1.0.0

SPDX-License-Identifier: MIT

Status: repository-local normative specification. Protocol version: `3.0.0`. Specification version: `1.0.0`.

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, and MAY are normative.

## 1. Scope and truth boundary

This specification defines a permissionless data and conformance interface for independently implemented Accountability and Partnership bonds. It is additive. It does not alter, replace, subset, extend, authorize, or deploy the canonical Base V3 contracts, SDK, API, x402 surface, governance policy, or supported-module closure.

A conforming implementation MUST label these five claims independently: `specificationCompliant`, `audited`, `deployed`, `authorized`, and `endorsed`. Specification compliance does not imply that an implementation is audited, deployed, authorized, or endorsed. Unless separately evidenced, the latter four labels MUST be false. No package artifact claims external publication.

## 2. Canonical authorities and identities

`mappings/canonical-v3.json` binds by path, SHA-256, module name, and exact final-source ABI identity to the current canonical repository surfaces. `interfaces/canonical-v3-interfaces.v1.json` is the self-sufficient, immutable compatibility snapshot of exact signatures, EIP-712 layouts, constants, states/transitions, source modules, SDK read/write routes, and API paths. It MUST NOT become a mutable competing authority or fallback. Implementations MUST compare full identities. They MUST NOT accept an ABI subset or superset as equivalent, route to V2, treat `latest` as V3, infer an address, or weaken a canonical disposition. The final SDK ABI tuple is exactly Accountability 36 (`0x0c18d05c868716fad4bfc1fcfad2da51c83f247de06a7e3871dcece768a9526f`), Partnership 55 (`0x954aeee609e92a621e726dcae77be193085651626941d582ca2f7f3b7c073d8c`), Governance 45 (`0xcf81d69fed252f21bfd7661ff53868aa81b9ce1a4a1c89edbec9eaabffa7ad0a`), and Mandate Registry 24 (`0xe31e9d196bf5a37c328313f688b0d6eff881847e6c46437c1fc617faff8e80e3`). Retired generic dispute, challenge, freeze, direct-settle, and dispute-payout selectors MUST NOT be advertised as callable Accountability capabilities. Drift MUST fail with `VF3-IDENTITY-001`.

The Partnership closure includes the read-only `FLOURISHING_MISSION()` and `FLOURISHING_NON_CONTROL_BOUNDARY()` constants. These constants describe non-control boundaries and MUST NOT authorize flourishing inputs to affect protected decisions. The Governance closure includes the read-only codehash bindings `canonicalRuntimeCodehash(address)` and `constructorPinnedPolicyTarget(address)`, the only-self append-only `pinCanonicalAddress(address,bytes32)` configuration selector, and only the codehash-bound `setCallPolicy(address,bytes4,bool,uint96,bytes32)` overload; the retired unpinned overload MUST be absent. Full ABI membership does not imply SDK write exposure. Governance configuration selectors, including address pinning, policy mutation, signer, timelock, and guardian-target configuration, MUST remain excluded from SDK write methods. The SDK governance write surface is limited to proposal, confirmation, execution, cancellation, guardian rotation acceptance/cancellation/proposal, and guardian pause operations.

The compatible bond kinds are:

* `accountability`: maps to SDK `AccountabilityBondTerms`, `AccountabilityBondReadModel`, and canonical `AccountabilityBondV3Safe`.
* `partnership`: maps to SDK `PartnershipBondTerms`, `PartnershipBondReadModel`, and canonical `PartnershipBondV3Safe`.

The canonical Base profiles are chain IDs 8453 and 84532. The current mapping truthfully records all supported identities as `not-deployed-not-authorized`; conformance MUST NOT upgrade that status.

## 3. Mission invariants

Every protected decision is custody, access, eligibility, pricing, slashing, settlement, disputes, or routing. A compatible implementation MUST enforce all of the following, directly and transitively:

1. Flourishing cannot slash principal. Flourishing, belief, reputation, trust score, behavioral routing, biometric, profiling, surveillance, quality, and loyalty inputs MUST NOT determine principal custody, slashing, settlement, access, eligibility, pricing, disputes, or routing.
2. Rewards cannot consume collateral. Reward assets and liabilities MUST be accounted separately from principal collateral. Reward issuance, fees, or insolvency MUST NOT reduce refundable principal.
3. Surveillance data is never required or permitted for protected decisions. Implementations MUST reject it rather than ignore, retain, transform, score, or forward it.
4. Consent is explicit. Both distinct participants MUST explicitly consent to exact terms, domain, chain, verifying contract, nonce, and validity bounds before funding or custody-affecting settlement.
5. Exits and refunds are bounded and pause-safe. Every nonterminal funded state MUST have a finite exit/refund bound. Expiry, cancellation/refund, force exit, and pull-credit withdrawal paths MUST remain available while ordinary operations are paused. Pausing MUST NOT extend a deadline, confiscate principal, or disable a matured refund.

The invariant object in each bond definition/state is mandatory and fixed. Contradiction fails closed with the corresponding stable mission code.

## 4. Bond definitions

Documents MUST validate against `bond-definition.v1.schema.json`, use lowercase 20-byte addresses and 32-byte hashes, represent every unsigned integer as a minimal decimal string, reject unknown top-level properties, and include explicit consent and invariant declarations.

Accountability definitions MUST use closed rule class 1/schema 1 and MUST bind the canonical source, source code hash, source/obligation IDs, deadlines, exact positive maximum slash, permitted evidence schema, privacy-exclusion hash, and empty signer-set commitments used by the current canonical source. Maximum slash MUST be no greater than company stake. Arbitrary mission, flourishing reward, generic evidence, reputation, or discretionary-remedy fields are prohibited.

Partnership definitions MUST use objective rule class 0/schema 0. Settlement MUST preserve total funded principal and MUST require both participants' exact bounded authorization. A third-party principal share and a principal-funded reward are prohibited.

## 5. State and accounting

The state names and ordinals map exactly to SDK `BondLifecycle` and Solidity `BondStateV3.State`. A compatible implementation MAY expose fewer transitions, but MUST NOT introduce a transition that bypasses consent, a deadline, or a terminal state. Terminal states are Settled, Cancelled, and ForceExited. Expired has only the bounded ForceExited recovery edge.

For every state report, exact conservation is REQUIRED: `principalLiability = refundablePrincipal + slashedPrincipal + lockedPrincipal` and `principalFunded = principalLiability + principalWithdrawn`; rewards are excluded from every principal term and `rewardBalance` MUST NOT exceed `rewardFunded`. For a Partnership bond, slashed principal MUST be zero. The embedded definition MUST independently validate and `definitionDigest` MUST bind its canonical bytes. Transition history MUST end at the reported state and every edge MUST be in the canonical transition table. When paused and a deadline has matured, an exit/refund path MUST remain callable. Pull credits remain liabilities until withdrawn.

`activePeriodEnd` is an exclusive boundary. The active period is exactly `[activePeriodStart, activePeriodEnd)`: ordinary active, settlement-request, challenge, finalizable, settlement-freeze, and `SettlementFrozen -> Settled` finalization transitions are permitted at `activePeriodEnd - 1` and prohibited at `activePeriodEnd` and later. Accountability enforcement uses consecutive half-open response, challenge, and decision windows. If `R = requiredBy`, their intervals are `[R,R+responseWindow)`, `[R+responseWindow,R+responseWindow+challengeWindow)`, and `[R+responseWindow+challengeWindow,R+responseWindow+challengeWindow+decisionWindow)`. The decision deadline MUST be strictly less than `activePeriodEnd`; equality is invalid.

An evidence request accepted before the exclusive end creates a bounded accepted liability. At or after `activePeriodEnd`, the permissionless timeout path MUST remain callable while paused and MUST re-read the codehash-pinned canonical source in the same timestamp immediately before economic resolution. If the canonical breach still exists, the timeout MAY perform the ordered source-valid finalization transitions at that same timestamp and settle only the pre-bounded accepted liability. If the breach no longer exists, it MUST cancel and credit a full principal refund. Same-timestamp transitions are invalid outside this typed timeout batch; stale, absent, differently timed, or outcome-inconsistent revalidation fails closed. The canonical transition closure contains exactly 25 source-valid edges, including `SettlementRequested -> Expired`, `Finalizable -> Expired`, `SettlementFrozen -> Cancelled`, and `SettlementFrozen -> Expired`.

## 6. Signed terms, domain separation, and replay protection

Signed terms MUST validate against `signed-terms.v1.schema.json`. The signed domain is exactly `{name:"Vaultfire", version:"3.0.0", chainId, verifyingContract}`; no `salt` member is accepted. Chain ID and verifying contract MUST equal the referenced bond definition. `termsDigest` is the SHA-256 of this package's canonical JSON bytes for the exact bond definition; this package digest is an interchange binding and MUST NOT be represented as the canonical contract's EIP-712 struct hash.

A production implementation MUST verify the canonical EIP-712 type layouts, domain separator, struct hash, digest, canonical low-`s` encoding, and recovered signer through the exact ABI/SDK snapshot in `interfaces/canonical-v3-interfaces.v1.json`. The offline package vectors exercise exact layouts, bindings, validity, participant sets, nonce scope, and signature encoding; they do not make an external signing or deployed-contract claim. Both participant signatures are required, recovered signers MUST be distinct and equal the consent parties, `validAfter <= observedAt <= validBefore`, and the definition nonce MUST equal the signed nonce. The tuple `(chainId, verifyingContract, signer, nonce)` MUST be consumed at most once and persisted atomically before a custody-affecting action. Replays, cross-chain reuse, cross-contract reuse, expired terms, and ambiguous or unrecoverable signatures MUST fail closed.

## 7. Receipts and errors

Receipts MUST validate against `receipt.v1.schema.json`, bind the canonical subject/evidence digests, and carry all five truth labels. A receipt is evidence of the stated observation only. It is not an audit, deployment, authorization, endorsement, payment settlement, or signature-validity claim unless separate evidence supports the corresponding label.

Errors MUST validate against `error-envelope.v1.schema.json`. Codes come only from `registry/error-codes.v1.json`. Codes are stable and MUST never be reassigned. New codes MAY be added in a minor specification release. Unknown failures MUST be mapped to `VF3-INTERNAL-001` and fail closed; internal details and sensitive inputs MUST NOT be emitted.

## 8. Deployment and capability evidence

Evidence MUST validate against `deployment-capability-evidence.v1.schema.json`. This offline package accepts source-only evidence: exact commit, tree, source-set digest, safe repository-relative regular-file paths, exact file hashes, exact ABI identity, a bounded observation interval, and false deployment/authorization/capability claims. Source availability is distinct from a deployment. A separate online profile MAY define positive deployment evidence, but `deploymentVerified=true` would require a non-null address and runtime hash, independently observed matching chain ID, exact ABI identity, exact runtime code hash, and independently bound observation provenance. `authorizationVerified=true` would additionally require a canonical authorization source. `capabilityVerified=true` would require both preceding claims and explicit capability evidence. This 1.0.0 offline schema rejects those positive claims rather than accepting unverified booleans. Claims MUST NOT be inferred from conformance. Null evidence is not positive evidence.

## 9. Conformance

A report MUST validate against `conformance-report.v1.schema.json`. `summary.conformant` is true only when every REQUIRED check passed, no check failed or was not run, source bindings match, all positive vectors pass, every adversarial vector fails with its expected stable code, and artifact determinism passes. Signature authenticity, deployment, authorization, audit, and endorsement remain separate claims.

The canonical corpus is the exact nonzero 8-positive/38-adversarial set identified by `registry/vector-corpus.v1.json`; empty, partial, reordered, substituted, or additional suites are nonconformant. `VF3-INTERNAL-001` is a harness/parser boundary and MUST NOT be an expected adversarial success. Each report check MUST carry its independently recomputed check-specific evidence digest. Report validation MUST recompute the vector-result implementation digest, validate the claimed Git commit object and its tree relationship, prove that the commit contains both `LICENSE` and `v3-open-spec`, and require a clean candidate for those paths. Until a final commit satisfies those properties, `specificationCompliant` and `summary.conformant` MUST be false.

Evidence and reports have no timeless validation mode. A validator MUST receive an explicit deterministic evaluation time for reproducible/offline evaluation or use production current UTC time. Source evidence MUST be current at that time and MUST have a validity interval no longer than seven days. Reports MUST be no older than 24 hours and no more than five minutes in the future.

Every protected decision input MUST bind to a reachable node in a closed, acyclic provenance graph. Nodes use only closed canonical contract-state/event source classes, immutable source/content bindings, parent digests, and typed canonical derivations. Self-cycles, all multi-node cycles, unreachable nodes, generic objective-source escapes, absent or opaque derivations, and recursively nested biometric, surveillance, profiling, behavioral, tracking, fingerprint, opaque, transitive, or hash-label extension content are prohibited regardless of benign keys or non-influential labels. Cryptographic authorization of a provenance graph is distinct from structural validity and is not claimed by unsigned test fixtures.

Signatures MUST have nonzero \(r\) and \(s\), \(r<n\), low-\(s\), and recovery identifier 27 or 28. Structural signature acceptance alone is not proof of signer authorization. A production conformance claim additionally requires recovery to the exact consenting parties and binding to terms digest, chain, verifying contract, participant, nonce, and validity bounds. Mutual settlement requires nonzero terms and authorization digests and exact binding to Partnership parties, bond, bond ID, chain, nonce, funded principal, and allocation.

State histories MUST start at `Uninitialized`, use only canonical edges, be contiguous, have strictly increasing timestamps, and end at the reported state. Refundable principal MUST reconcile exactly to unique pull credits held only by bond parties. Every funded refundable state, including a matured nonterminal state, MUST expose a bounded exit callable while paused.

The complete REQUIRED check-ID set is machine-readable in `registry/conformance-checks.v1.json`. A report MUST contain every ID exactly once and MUST bind each result to a nonzero evidence digest. Arbitrary caller-supplied check names, duplicate IDs, omitted checks, `not-run` checks, and summary/truth mismatches are nonconforming.

## 10. Canonicalization and digests

Canonical JSON uses the repository's `RFC8785-repository-subset-v1`: UTF-8; object keys sorted by Unicode code point; no insignificant whitespace; arrays retain order; strings use JSON escaping; booleans/null use JSON literals; and protocol integers are minimal decimal strings. Floating point values, `NaN`, infinities, unpaired surrogates, integers outside the supported 256-bit magnitude, and JSON integer values in protocol documents are prohibited except schema-defined bounded counters in reports. Duplicate keys MUST be rejected by parsers. Artifact SHA-256 is over exact file bytes. `ARTIFACTS.sha256` is sorted bytewise by relative POSIX path and covers every regular source artifact plus the root license. It excludes itself, the generated post-commit report, and ephemeral interpreter/test caches. Development discovery ignores `.pytest_cache`, `__pycache__`, and bytecode; release mode MUST reject them. Package symlinks are prohibited.

## 11. Versioning, extensions, compatibility, and deprecation

Specification and schema versions use Semantic Versioning. Patch releases clarify or tighten validation without adding valid semantic behavior. Minor releases may add optional `x-` extension fields, schemas, or error codes while preserving all mission invariants. Major releases may be incompatible but MUST use new schema IDs and MUST NOT silently reinterpret 1.x documents.

Unknown fields are rejected except within the explicit `extensions` object. Extension names MUST match `x-<lowercase-hyphenated-name>`. Extensions MUST NOT alter required field meaning, canonical identities, accounting, consent, truth labels, protected decisions, or mission invariants. Security-critical extension data MUST be explicitly standardized before use.

Deprecation requires a minor release notice identifying feature, replacement or absence, rationale, earliest removal major, and at least one full minor-release compatibility interval. Security prohibitions may take effect immediately, fail closed, and are not weakening changes. Deprecated behavior MUST never fall back to V2. Removed behavior returns `VF3-DEPRECATED-001`.

## 12. Open license and production truth

The repository root `LICENSE` is the authoritative MIT License for the Vaultfire V3 code and this open interface specification. Its exact SHA-256 is `6ffb9af0a5ff2c17d0bbcb866634076f7bcd0f82ce756bd80856398ef67dd42a`; implementations and distributions claiming this package license MUST bind that exact file and digest. Package source files state `SPDX-License-Identifier: MIT` where the format supports it. Missing, modified, substituted, or stale license bindings MUST fail closed with `VF3-LICENSE-001`.

Open licensing grants the permissions stated in `LICENSE`; it does not prove or imply production deployment, decentralization, distributed control, governance assignment, module activation, audit, authorization, endorsement, operational readiness, or censorship resistance. Those remain separately evidenced truth claims and default false.

## 13. Core-product architecture, modular controls, and activation

Accountability and Partnership bonds are the core product. Identity, evidence, payment, governance, and enforcement modules are supporting infrastructure and MUST remain bounded to the minimum authority required by a bond operation. Supporting infrastructure MUST NOT become an independent source of subjective protected-decision authority.

Every compatible V3 module MUST enforce bounded assets and liabilities; a pull-payment claim pattern wherever value can be claimed; explicit consent for participant-authorized effects; terminal states and finite exit/refund bounds; immutable content, code, domain, and evidence bindings; fail-closed APIs for missing, stale, malformed, unknown, or mismatched inputs; and exact-commit tests that bind tests to the exact reviewed source/artifact commitment rather than a compatible-looking substitute. A module that does not claim or transfer value MUST still prove that value claims are absent; it MUST NOT silently add a push-payment surface.

Activation MUST occur independently, module by module, behind a default-closed gate. Each gate MUST bind the exact module identity, code/artifact commitment, chain, capabilities, caps, consent/authorization state, evidence freshness, monitoring, rollback/pause readiness, and truth labels. Passing one module gate MUST NOT activate another module. A monolithic, transitive, wildcard, inferred, or uncontrolled launch is prohibited and fails with `VF3-ACTIVATION-001`. Source support or specification conformance alone MUST NOT open an activation gate.

## 14. Cross-chain trust-history portability

A compatible implementation MAY port a cryptographic commitment to trust history between chains, but MUST NOT port raw behavioral, surveillance, biometric, profiling, secret, or personal data. The source-chain history digest MUST be immutable and content-addressed. The subject's explicit consent MUST bind source chain, destination chain, history digest, permitted purpose, recipient, and validity bound. Destination-chain use MUST obtain fresh chain-specific authorization and MUST apply that chain's canonical module identities, deployment evidence, capability gates, and replay domain. Source-chain authorization, deployment, reputation, or consent MUST NOT be treated as destination-chain authorization.

Portability MUST preserve data minimization, unlinkability where feasible, selective disclosure, revocation/expiry semantics, and the prohibition on unsafe inputs for protected decisions. A portable history commitment is supporting evidence only; it cannot weaken privacy, consent, bounded liability, or chain-specific authorization and cannot itself authorize custody, slashing, settlement, access, eligibility, pricing, disputes, or routing.
