Canonical data-contract ownership and freeze plan

Status: reviewed engineering design, 2026-09-19; bytes not frozen; executable conformance not run. This document assigns authority and freeze gates for the canonical contracts. The encoding contract supplies the revision-1 primitive widths, tags, field order, wrappers, state schemas, named bounds, and vector design. This file records the selected engineering design. It does not claim an accepted release, calibrated values, generated fixtures, or executable conformance.

1. Authority and status

The authority order is: normative specification and accepted decisions; the reviewed encoding contract; canonical Rust schema and release types as executable authority; the versioned format manifest as a record of revision, tags, domains, pins, and artifact digests; reviewed conformance vectors; implementation consumers. Commonware v2026.9.0 (d476a2361ce6840d2b9d0aa6fb30a924429046d4) is the Makechain library baseline. Working HEAD 3827a56dc76818bd31c42c2d6b8c7da261123f2a is research input only: codec, Merkle, BMT, and QMDB have material changes after the pin, so HEAD must never silently define bytes.

The encoding contract owns every approved field sequence, primitive width, collection bound, enum tag, domain prefix, library type and pin, profile identifier, and schema version. Canonical Rust types implement that contract. The format manifest records the selected identifiers and artifact digests; it is not a schema DSL and does not generate Rust. Transport schemas, SDK metadata, wasm bindings, and documentation are generated from the Rust registry and checked against reviewed vectors; none maintains a parallel registry.

2. Encoding foundation

Pinned source evidence matters here: commonware-codec offers fixed-width integer primitives and separate varint wrappers; it does not choose the representation for a Makechain field. Its usize wire form is varuint restricted to u32, which is useful evidence for collection framing but is not a protocol field type. The companion encoding prose and vectors must make these choices reproducible without Rust. At v2026.9.0, the exact evidence is in codec/src/lib.rs (configured read and exact-consumption decode), codec/src/types/primitives.rs (big-endian primitives, bounded usize, booleans), codec/src/varint.rs (shortest-form unsigned and ZigZag varints), and codec/src/types/vec.rs (counted, configured vectors).

3. Canonical artifact inventory

state_root is Makechain's canonical current-state commitment. state_target {ops_root,floor,size} is the Commonware persistence/sync target and is not interchangeable with it. Likewise, membership_target {root,floor,size} and history_target {root,size} are distinct authenticated member targets. Implementations must not flatten these into an undifferentiated root tuple.

4. Commands and witness placement

Encoding §§2–5 allocate every command and subvariant tag, payload field order, authorization class, and evidence placement. The Rust registry adds the collection-bound and resource-shape references and links positive and negative fixtures.

For PUSH, the signed intent owns project ID, commitments, ref names, expected revisions, and targets. Exactly one unsigned membership witness accompanies each non-delete ref operation in ref operation order; DELETE has none. Witness variants are SameCommand(index), Location(loc), and Proof(anchor_size,loc,inclusion_proof). A gateway may replace only this evidence within signed resource/charge bounds. Replacement preserves intent_digest and changes command_id.

Authorization witnesses and signatures also live outside CommandIntent, but bind its digest using their family profile. Different sufficient root approval subsets are valid different envelopes. The encoding contract and canonical Rust registry specify the SignedCommand split directly, rather than infer signed versus unsigned fields from a UI or RPC request.

In the fixed development profile, CMD-17 and consensus-critical transitions of CMD-16 are unavailable and deterministically rejected at admission and execution. Their canonical schemas and reserved tags still exist so the development profile cannot reinterpret those bytes. Encoding §2 fixes their revision-1 numeric tags. Neither a local feature flag nor a successful no-op can waive these rules.

5. State identity and value contracts

The required families are AccountLedger, AccountRoot, DelegatedKey, Project, ProjectMetadata, SlugClaim, ProjectRole, TransferOffer, Ref, UsernameLease, AccountUsername, SettlementAnchor, ProtocolReleaseEntry, ProtocolScheduleState, and ValidatorScheduleEntry—fifteen families. Encoding §6 defines each domain prefix, full identity field sequence, value field sequence, schema selection rule, and record class. The Rust registry binds each to its named maximum and command ownership. ProjectMetadata and Project, for example, remain separate keys even though both use project identity.

6. Digest and domain registry

The registry records ASCII bytes, preimage schema ID/revision, hash algorithm, digest width, and first release/profile. A vector must distinguish concatenation boundaries through the canonical preimage schema; prose such as A || B is insufficient when either side is variable length.

7. Block members and proof contracts

Proof serialization uses the exact pinned native Commonware proof codec and its configured item, cardinality, and aggregate byte bounds. Makechain owns the enclosing proof kind, anchor and context, not a rewritten sibling path. Vectors must cover library empty root, one leaf, odd-leaf duplication, multiple counts, boundary positions, wrong count/index, reordered/extra/missing siblings, and exact decode/re-encode bytes.

8. Signature and external-format profiles

Tempo settlement evidence has its own profile ID and source pin. It must not inherit Makechain's Commonware pin merely because selected certificate/proposal/round/signature bytes currently match. The Moderato fixture must decode, re-encode identically, and verify under both the current Tempo profile and a proposed target before a pin change. No in-band version sniffing or current Tempo HEAD may select a certificate decoder.

The settlement-source profile is also canonical data. It binds the Tempo chain ID, settlement contract address, pinned immutable runtime code identity, beneficiary storage-slot derivation, value width, contract-state layout/version, state-root/account/storage-proof semantics, accepted asset policy, Tempo threshold public identity, certificate profile, and evidence timing bounds. The accepted launch contract is non-proxy with immutable logic; its account proof must match the pinned runtime code hash. No implementation-slot proof or upgradeable fallback is admitted. Dedicated deployments are selected for Moderato and mainnet, leaving the existing deployment intact. The settlement interface fixes the engineering layout and proof inputs; its numeric proof bounds remain provisional, while exact runtime bytes/hash and deployment inputs remain to freeze.

No environment has precredited accounts. Devnets and qualification testnets import credits only from real Tempo Moderato proofs; mainnet uses the reviewed Tempo mainnet profile. The existing StorageRelay.sol at contract repository commit 13945e9 is not compatible as-is: it proves one global issuedUnits, emits per-rent data rather than storing a monotonic cumulative per beneficiary, contains an operator credit path, permits payment-token replacement, and is UUPS upgradeable. Its receipt/log replay scheme is not the required settlement state proof. The reference codebase's separate crates/makechain-tempo-proof/src/lib.rs may be reference material only for the Tempo certificate/header leg; it does not make the existing receipt proof leg compatible. No fixture may fabricate a positive proof from that incompatible layout.

9. Executable authority and fixture program

Canonical Rust schema and release modules should provide or generate:

1. Canonical types/codecs, domain constants, discriminants, and decode configurations that directly implement the reviewed encoding contract.
2. The native reference encoder/verifier and the same Rust verifier compiled to wasm.
3. Human-readable encoding tables, transport bindings, and machine-readable SDK metadata generated from the canonical Rust registry.
4. RPC byte wrappers and display schemas, without making RPC JSON canonical.
5. Positive, boundary, cross-release/profile, and negative fixture manifests.

TypeScript may provide ergonomic builders and decoded views, but signing and proof verification use the native/wasm Rust contract rather than a hand-copied canonical codec. A format release is accepted only when derived outputs are reproducible and native/wasm bytes, hashes, verification results, and error categories agree.

Before canonical serialization is frozen, a fixture file may use this noncanonical semantic envelope:

FixtureCase {
  fixture_id, contract_id, schema_revision, profile_id, ruleset_id,
  source_pins, semantic_input, expected_canonical_hex?, expected_digests?,
  expected_result {accept | reject(error_class)}, negative_mutation?, notes
}

This JSON/YAML test-data envelope is never signed or hashed. Numeric semantic values use decimal strings where host JSON ranges differ; bytes use lowercase even-length hex. A missing expected byte field means the wire contract is unresolved, not that empty bytes are expected. Once frozen, every accepted vector includes canonical bytes and decode/re-encode equality.

Required negative families are: truncation/trailing bytes; invalid bool/tag/option; nonminimal or overflowing integer/length; excess nesting/count/bytes/work; non-increasing or duplicate ordered members; wrong domain/chain/profile/ruleset; state key/identity mismatch; malformed/high-S or wrong signature presentation; WebAuthn reserialization/origin/challenge/flag errors; witness count/order or target mismatch; missing/mismatched genesis epoch-info/hash pairs, post-genesis presence, and wrong dynamic-genesis Payload::EpochInfo projection; BMT count/index/sibling errors; target/root mismatch; certificate under the wrong pin; proof/service-outcome confusion; fixed-profile epoch other than zero; and profile-disabled membership or consensus-critical release commands.

10. Contract-freeze and qualification matrix

Implementation can start after its owned contracts have fixed schemas, bytes, bounds, ownership, and expected vector cases. Generated native/wasm artifacts and executable parity are later qualification outputs, not prerequisites for writing them. An unresolved contract row is not permission to choose a convenient integer, tag, field order, default, or library HEAD representation. The unresolved settlement deployment blocks positive import qualification and enabling that command, but it does not block independent codec, state, executor or proof work.

The specification allows no genesis credit allocation and no pre-created credit ledger (§5.2). Genesis has no account credit ledgers; the first usable flow is proof-backed IMPORT_CREDITS, then INIT_ACCOUNT. Dedicated contracts are selected for both Tempo networks; each exact contract/proof profile has a pinned candidate certificate type and still needs its deployment manifest and authentic fixtures. The canonical schema can be implemented before those deployment inputs exist.

11. Source ledger