Makechain operating envelope

This document defines the conditions the architecture must be designed and qualified to support. It does not select process topology, machine profiles, storage products, command limits, prices, or deployment defaults. Numeric values from the specification are identified as protocol parameters or analytical derivations; they are not production measurements.

1. Status vocabulary

Every consequential claim in this document uses one of these classes:

Unknown values are written as TBD, with an owner and resolution condition. A target remains unqualified until a measured result under its stated workload meets its acceptance rule.

2. Accepted launch boundary and sequencing

The eventual launch scope is fixed by owner decision:

• Validator, exporter, store and proof service, admission, indexing/query, and settlement-relayer services.
• Rust verification library and wasm verifier.
• TypeScript SDK and CLI.
• Minimal explorer and documentation website.
• Integration with mkit and the per-project availability layers.

Rich collaboration and social applications are outside the protocol launch requirement. The owner's consuming application is maintained in a separate, unrelated project. Makechain defines and validates its integration contracts but does not implement or duplicate that application's business logic.

Initial development is protocol first: protocol definitions, deterministic execution, Commonware integration, storage and recovery, consensus and DKG, signing, proofs, and only the fixtures, harnesses, and minimal adapters needed to qualify them. Product SDK, user-facing CLI, explorer, website, and broad service implementation follow after their protocol contracts have evidence and stability. Native/wasm verifier qualification remains an early concern because it can reveal wire, encoding, signature, or proof incompatibility.

The following workflows must be represented in workload models and later end-to-end qualification:

1. Prepare, sign, submit, finalize, and verify a command.
2. Store an object closure, finalize each required publication, and reconcile both outcomes without treating either as proof of the other.
3. Create, update, and delete refs with membership witnesses and atomic state transitions.
4. Change authority: configure roots, authorize/revoke keys, manage roles, and transfer projects.
5. Import settlement credits from a finalized external proof.
6. Schedule and activate protocol releases and validator-set changes, including DKG and restart.
7. Serve current-state, command, publication, membership, and finality evidence against authenticated headers; rebuild derived views from certified inputs.
8. Restart, catch up, bootstrap, and recover history gaps without changing finalized results.

3. Owner decisions and accepted answers

O1 and O2 are resolved; O3 establishes the latency aspiration and O4 establishes research-first placement. Their detailed acceptance conditions and the remaining questions can be sharpened using early characterization; before P1 exits, resolve them or record an explicit deferral with an owner and revisit trigger. O3's measurement-first percentile selection is resolved sequencing, not an unanswered owner question or a prerequisite for P2. Trusted operation does not change the protocol's n = 7, f = 2, quorum 5 assumptions: one correlated administrative, credential, or custody compromise affecting more than two identities exceeds the Byzantine fault bound, and loss of three identities halts liveness. The owner accepts organizational trust in the admitted operators; infrastructure separation remains an availability and compromise-containment concern.

For O3, the owner initially considered p95 5 seconds / p99 15 seconds under sustained heavy load as an acceptable throughput-prioritized fallback, then clarified that the design should aim for subsecond finalization, ideally around 500 ms. The clarified subsecond aspiration is the primary direction. Neither set of numbers is a production-qualified objective until the measurement boundary, percentile, workload, and acceptance rule are fixed and supported by evidence. The owner chose to select the percentile after initial measurements. Report p50, p95, and p99 for both T2a and T2b during characterization; then agree the target and evaluate it in subsequent qualification runs. No 500 ms p95 commitment has been accepted.

4. Representative workload scenarios

These scenarios describe shapes, not promised rates. The selected O2 priority determines the first qualification profile; it does not remove the other scenarios.

For W1-W4, define both a steady interval long enough to expose queues, compaction, and cache effects and a burst interval that tests bounded overload and recovery. Their durations and rates are calibration items until characterization provides evidence.

4.1 Proposed low, medium, and high workload bands

The owner accepted using three sizing bands as planning assumptions for review, but has not accepted the numeric values below. They are synthetic qualification inputs, not a demand forecast, capacity claim, launch commitment, or pricing basis. Keep the same generated intents and seed when comparing implementations or topology candidates.

Use one command-intent mix in the first comparison: 80% PUSH, 12% account/project/key/role lifecycle, 4% username, and 4% credit import. Release, validator-schedule, and DKG transitions are rare boundary scenarios under W4 rather than artificial steady traffic. Within PUSH, include both independent signing slots and shared-slot contention; measure stale-CAS and sequence failures instead of assigning them a success rate in advance.

Let A be agents, u publication intents per agent per minute, rho retry/duplicate overhead, c_bar mean commitments/PUSH, d successful-path proof/receipt requests per finalized PUSH, q successful-path query reads per finalized PUSH, a/x resident-key additions/removals per finalized distinct command, s the observed fraction of distinct PUSH intents that finalize, and D_fin the observed finalized distinct-command rate. With PUSH share 0.8 and a 3x burst:

distinct PUSH/s                 P = A * u / 60
distinct command intents/s      D = P / 0.8
offered command requests/s      O = D * (1 + rho)
burst offered requests/s        O_burst = 3 * O
finalized PUSH/s                 P_fin = P * s
permanent membership leaves/s   L = P_fin * c_bar
successful-path proof requests/s E_success = P_fin * d
successful-path query reads/s    Q_success = P_fin * q
net resident-key growth/s        N = (a - x) * D_fin
availability ingest bytes/s      V = U * measured mean deduplicated bytes/accepted upload

U is the independently measured rate of accepted availability uploads, summed over every layer a client writes to, because a project may be served by several. Uploads precede chain finalization and may never lead to a finalized PUSH; measure their bytes and staging retention independently rather than deriving ingestion from P_fin.

The table below is conditional on every distinct intent finalizing (s = 1, D_fin = D). It is a fixture-shape calculation, not predicted receipt traffic under rejection or contention. During a run, derive successful receipt/proof/query traffic and growth from observed finalized commands. Count status polls, proof attempts for nonfinalized or Unknown intents, witness refreshes, and retry or reconciliation requests separately as offered service traffic; do not infer them from P_fin.

These bands are not yet runnable manifests. P3 must bind each fixture to the canonical schema and vectors and record at least:

The high band's 100 PUSH/s is an exploratory anchor, not a capacity ceiling or owner commitment. After short fixed-rate runs, use a bounded saturation ramp: hold command shape, prepared/history state, and topology constant; increase concurrency or offered rate in controlled stages; and predeclare queue, memory, and durability-backlog bounds plus rejection/defer behavior. Stop at the first sustained knee where admitted/finalized work no longer tracks offered work, a latency boundary breaches its campaign target, bounded queues do not drain, durability backlog persists, or a correctness fault occurs. Record offered, sent, admitted, finalized, distinct, retry, status, and proof traffic at every stage, followed by recovery. Do not extrapolate capacity past the last measured stable stage.

The first harness proposal is 10 minutes warm-up, 30 minutes steady, 5 minutes at 3x, and 30 minutes recovery; add a four-hour medium soak after short runs are stable. These durations are also reviewable planning assumptions. Report actual accepted/finalized rates and recompute growth from finalized data. Membership operations add one commit operation per finalized block to L; yearly growth integrates the reviewed duty schedule rather than running a peak band for 365 days.

5. Workload units and derivations

The workload manifest for every measurement records at least:

Also report distinct successful intents/s, finalized command and publication occurrences/s, unique (project, commitment) pairs/s, duplicate ratio, retries/intent, and every admission/selection outcome. Reconcile each selection cohort as selected = included + dropped + still deferred at its observation cut; do not subtract flows across intervals without accounting for backlog.

Let r_k(t) be the command rate for kind k, m_k its traffic fraction, c commitments per PUSH, q ref operations per PUSH, and g_f gross protocol creation events of record family f per command (distinct from the conservative new_records reservation). Let A_f,I count keys absent at the start of interval I and resident at its end, and X_f,I count keys resident at the start and absent at its end. A same-key replacement is still a gross creation event but is neither A nor X. Use checked integer totals in the harness; these formulas communicate the derivation:

total command rate                 R = sum_k r_k
traffic mix                       m_k = r_k / R; sum_k m_k = 1
commands over interval I          C_I = integral_I R(t) dt
commitment leaves over I          L_I = sum over finalized PUSH commands of c
ref operations over I             F_I = sum over finalized PUSH commands of q
gross logical creation events     G_f,I = sum over finalized commands of g_f
resident-key delta, family f      delta N_f,I = A_f,I - X_f,I
permanent-record delta            delta N_perm,I = A_perm,I
membership operations             M_I = L_I + one commit operation per finalized block
reserved canonical byte load      Q_I = sum over finalized commands of reserved block_bytes
published/transport encoded bytes Z_I = sum of encoded bodies + headers + certificates + framing
availability ingest               V_I = sum of accepted object-closure bytes after service deduplication rules
membership window at peak rate    H_member,plan = membership_window_operations / peak membership_operations_per_second
marshal retention at peak rate    H_marshal,plan = retained_marshal_blocks / peak finalized_blocks_per_second

Annual projections use the same sums over the declared expected yearly traffic schedule, rather than multiplying a peak rate by a year. Sensitivity output must show at least the expected schedule, the accepted burst schedule, and a higher stress schedule; none is capacity until measured.

Report reserved creation upper bounds separately from actual gross creation events; optional branches may reserve more than they create. Resource reservation follows the protocol's independent dimensions: canonical block_bytes, reserved work_units, and gross new_records. Deletions do not offset creation reservations and dimensions do not convert into one another. Prices, hard limits, and work weights remain calibration items owned by the chainspec and release process.

Q_I is the validity-resource dimension; Z_I sizes stored and transferred artifacts and must not be compared directly with max_block_bytes. The two retention equations are planning envelopes at the declared peak rate, not guaranteed wall-clock lower bounds: a higher realized burst or rapid catch-up after a stall can turn the windows over faster. Qualification must measure those cases, witness-refresh bytes/work after a reference falls below the membership window, and the submitted/ admitted/finalized amplification caused by stale-CAS retries, sequence contention, rebroadcasts, and duplicate intents.

6. Acceptance targets and exact measurement boundaries

Numeric cells are either an explicitly labeled owner aspiration with unresolved scope or TBD. Report distributions and failure counts, not only averages. Steady and burst targets may differ, but both use the same boundary definitions. Each result states offered load and traffic mix and includes every attempt; it never computes latency only from requests that succeeded.

T2b is the primary user-facing latency expectation requested by O3. With seven validators, admission Accepted uses f + 1 = 3 effective-validator acknowledgements while finality requires quorum 5; the two observations cannot be substituted. Wall-clock or consensus timestamps may be recorded as context but are not subtracted to calculate latency. Accepted is not finality; consensus finalization, later durable progress, and later receipt availability are separate observations. A complete user push also requires a durable storage acknowledgement from each availability layer the client uploads to, measured independently from T2a-c and T5.

The supported outage envelope must separately state:

• which validator, region, cluster, network, credential, and operator failures may be simultaneous;
• which combinations must retain safety only and which must retain both safety and liveness;
• maximum planned/unplanned absence before restart, catch-up, or fresh bootstrap is required;
• which external-service outages may delay admission, proofs, queries, settlement, or availability without changing consensus validity.

6.1 Recovery objectives and reset policy by environment

The owner explicitly accepts destructive resets of pre-mainnet devnet and qualification testnet, provided every reset creates a new chain identity. Test history, balances, credits, and namespaces need not survive those resets. This permission does not turn deletion of a sync marker, partial database replacement, or validator-identity reuse into a supported recovery procedure.

Accepted development direction (owner, 2026-09-19), incorporated in specification revision 4: use the source-supported fixed epoch-zero composition with seven genesis validators and an unchanging committee. Provision one trusted-dealer threshold output and one share per validator at genesis; retain the production-shaped threshold VRF, Random V1, Stateful/Deferred path, three database members, Makechain executor, and proof/receipt path. Omit the epoch orchestrator and continuous reshare actor. A genesis-bound profile must deterministically reject validator-set scheduling and consensus-critical releases that require a future epoch; they cannot be accepted as no-ops. The source basis is architecture evidence ↗ (external site) and its pinned Commonware contracts, plus the Constantinople fixed-epoch assembly cited in §9.1. This profile narrows early tests to deterministic execution, storage, consensus, restart, and proofs. It does not qualify DKG/reshare, epoch boundaries, membership transitions, production custody, or recovery topology, and it does not amend the mainnet specification. The owner accepted a reset to real bootstrap DKG and reshare qualification after the fixed development stage. Qualification testnet must exercise those specified paths before mainnet readiness.

Recovery objectives are staged decisions. Before each campaign, record either a proposed planning target for the T6-T9 boundary under test or a dated deferral with an owner and evidence trigger. Unknown production topology, cost, and recovery values do not block P2 module and interface design; they do block the affected recovery qualification, production placement approval, and mainnet readiness.

The sequencing boundary is deliberate. Devnet work first proves protocol correctness, canonical bytes, propose/verify/apply parity, roots, rollback, restart, and proof verification. Qualification testnet adds realistic persistence, failures, epochs, publication, and topology experiments. Mainnet is gated on security hardening: durable and erasable SecretStore custody, least-privilege credentials, audited signer fencing, environment isolation, monitored recovery sources, and practiced runbooks. Passing a disposable correctness test does not satisfy a mainnet hardening gate.

7. Resource and retention calibration matrix

For resident state, report both logical and allocated memory:

resident bytes ~= sum_f(live_records_f * measured_allocated_index_bytes_per_record_f)
                  + activity_bitmap + grafted_tree + bounded_caches
                  + speculative_headroom + rebuild_headroom

For yearly retained growth, sum measured encoded sizes by artifact and apply only reviewed replication factors. Keep logical bytes, allocated bytes, transfer bytes, and replicated billed bytes as separate columns. Do not extrapolate store or availability cost from validator retention.

8. Topology and failure-domain questionnaire

Complete O4 and O6, and make the consequences of accepted O1 explicit, before selecting deployments:

Seven validator processes are intentionally not seven independent operators. They remain seven logical identities under one accepted trusted-operator model. If the outage objective requires liveness through loss of any one infrastructure domain, no such domain may contain more than two of the seven identities; a 3/2/2 placement would halt on loss of the three-identity domain. This is a constraint to evaluate after O4, not a selection of regions, clusters, or products. A validator identity has exactly one active signer; ambiguous failover halts rather than risking two signers.

P1 decides the outage objective, simultaneous fault/maintenance allowance, the failure-domain meaning for the two store copies, and restart and publication-outage objectives. P4 later selects exact regions, projects, clusters, storage, fencing, SecretStore custody/erasure, and recovery procedures.

8.1 Cost/latency topology comparison before placement

The owner selected one GCP region for the first disposable seven-validator devnet on 2026-09-19. Seven distinct identities/shares and fenced durable validator stores remain mandatory; a region outage stops that devnet. Exact region, zone placement, and production topology remain open. For production qualification, no topology candidate or zone/region-loss guarantee is selected. Compare each candidate with the same seven-validator workload, machine class, storage profile, history age, and test seed. Record fifth-fastest vote/certificate path latency, T2a/T2b percentiles, inter-domain bytes, required clusters/projects, storage replicas, recovery traffic, and operator complexity; obtain current prices only when turning measured resource use into a budget.

The comparison reports cost drivers rather than prices: validator and cluster count, inter-region egress, replicated persistent bytes, store and mirror duplication, load-balancer and observability surfaces, operator time, and recovery transfer. A topology advances only if it meets the eventual latency and recovery objectives with headroom under medium and high bands; a fast empty-block result or a low average RTT is insufficient.

9. Measurement-first qualification method

Before promising numeric capacity or latency:

1. Instantiate accepted O2 as a workload manifest with expected, burst, and stress profiles; resolve O3/O4/O6 before treating those profiles as acceptance targets.
2. Characterize one dimension at a time to locate byte, work, creation, storage, proof, and queue limits; then run mixed scenarios that expose contention between them.
3. Record revision and protocol parameters, topology, machine/storage/network profile, dataset and history age, workload seed, warm/cold state, duration, offered and completed load, and artifacts.
4. Measure resource use and latency distributions at the boundaries in section 6. Include errors, timeouts, queue depths, lag, recovery after the burst, and correctness checks.
5. Repeat failure/restart tests at controlled crash points. Verify roots, replay marks, deposits, watermarks, proof results, and identity fencing rather than accepting process readiness alone.
6. Convert a measured knee or limit into a proposed operating point with stated headroom. Owner review turns it into a target or calibrated parameter; the evidence remains environment-specific.

Source inspection and analytical sizing may validate formulas or library behavior, but they cannot establish assembled throughput, tail latency, recovery time, or production capacity. No benchmark output or source-inspection note by itself marks an architecture qualification item as passed.

Pinned source inspection used for this draft (not qualification evidence):

9.1 Sub-second finalization: source evidence and comparison to qualify

Owner direction is subsecond finalization, ideally around 500 ms. This is an architecture goal, not a demonstrated result. The earlier 5s p95 / 15s p99 choice is a throughput-oriented fallback, not permission to optimize only for multi-second latency. The accepted sequence is to characterize p50/p95/p99 first and select the target percentile from those measurements. Workload scope remains a separate reviewed input. This is not pending owner input before characterization or P2. Characterize both internal consensus and client submission-to-verified-finality boundaries; the owner has not accepted a 500 ms p95 commitment or a consensus-only promise. Revisit the acceptance rule when the measured distributions and workload are available.

All Commonware citations below refer to v2026.9.0 at the commit listed above, read using git show v2026.9.0:<path>, rather than the newer working checkout.

The reference codebase's README subsecond-finality and approximately 200 ms block statements were also checked. They are not equivalent to a reproducible 500 ms client-finality result. Its checked-in bench/baselines/pre-testnet-baseline.md:38-48 reports a different, small local-Docker experiment; docs/design/makechain-protocol-redesign-validated.md:525-533 reports block cadence and application work, not the same end-to-end boundary. These are historical context only, never architecture or performance baselines for the new chain.

Recommended qualification comparison, not permission to change the specification or run experiments:

1. Use the specified Random/rotating + Stateful/Deferred configuration as the baseline with real Makechain PUSH execution, three database members, signatures, proofs, and durable acknowledgements.
2. Compare a candidate RoundRobin stable-term configuration with bounded optimistic lookahead. Changing elector or term length requires an explicit protocol decision; after launch it follows the consensus-critical release procedure. Keep the same workloads and topologies for comparison.
3. Sweep proposal batching delay/size, pending-work bounds, storage/network profiles, and verification concurrency without changing serial application semantics. Measure sustained useful throughput and foreground latency during bulk imports, not only small empty blocks or saturated block cadence.
4. Record admission/queue time, proposal construction, body dissemination, execution/Merkle and persistence gates, notarization, certification, finalization, readable state, database durability, proof delivery, and client verification. Overlapped stages are not added as if they were serial. Low finalization latency cannot be inferred from a high blocks-per-second count.
5. Exercise failed and selectively censoring leaders, term skips, delayed finalization, epoch/DKG boundaries, restart, abandoned speculative state, and publication backpressure. Include memory and bandwidth costs of lookahead and high block cadence in the same comparison.
6. Compare candidate network-latency matrices and costs before placement. Both the quorum path and rotating leader location matter; faster five-of-seven quorum formation may coexist with slow outliers whose queues or recovery costs make the topology unsustainable. No region/zone survival promise follows from a fast healthy-path result.

Review the incorporated §13.8 rationale correction and baseline-versus-candidate qualification results separately. The factual correction does not, by itself, select stable terms or establish 500 ms feasibility. P1 owns the goal and comparison requirements; P2/P6 own integration design and executable qualification. No benchmarks have been run in this planning pass.

10. P1 exit checklist

• [x] Eventual launch services/clients and the external consuming-application boundary are recorded.
• [x] Protocol-first development sequencing and required protocol workflows are recorded.
• [x] O1 trusted, permissioned validator-operator model is accepted; infrastructure/custody correlation and outage objectives remain open under O4/O6.
• [x] O2 heavy concurrent agent publishing is selected as the primary qualification workload.
• [x] O3 subsecond/~500 ms latency aspiration is recorded for T2a/T2b; measurement-first percentile selection is accepted sequencing; workload scope and the final acceptance rule remain to review.
• [x] O4 placement follows cost/latency research; no zone/region guarantee is implied and recovery objectives remain open.
• [ ] Expected, burst, and stress manifests have reviewed numeric values.
• [ ] Command rates, traffic mix, PUSH/ref batch distributions, and proof/query traffic are stated.
• [ ] Account, project, resident-record, membership-operation, availability, and yearly store-growth projections are derived from stated inputs.
• [ ] T1-T9 planning targets needed for the next campaign are accepted or have dated deferrals; mainnet objectives remain a readiness gate.
• [ ] Restart, bootstrap, store recovery, and history-source obligations have a next-campaign target or dated deferral and a mainnet gate.
• [ ] Every consequential target links to a future measurement and an architectural constraint or owner.
• [x] All analytical estimates remain labeled; no unmeasured number is presented as demonstrated capacity.
• [ ] Protocol owner and architecture lead review the envelope and record remaining deferrals with an owner, consequence, and revisit trigger.

P1 exits only after this checklist is reviewed. It does not require production measurements or production-cost inputs to exist, but it requires targets, assumptions, formulas, planned evidence, and owned dated deferrals to be distinguishable. Those deferrals may authorize P2 module and boundary work; they still block the affected qualification campaign, placement approval, or mainnet readiness.

11. Design-review disposition and owned deferrals

Architecture review date: 2026-09-19. The protocol-first scope, trusted operator policy, fixed devnet, real Tempo funding, one-region first placement, and the exoware store with a GCS mirror are selected. The synthetic bands and formulas above are suitable inputs for implementation and harness planning; they are not owner workload commitments, accepted production capacity, or calibrated chain limits. The following deferrals close the design phase's ownership questions without inventing measurements.

Every deferral carries this review date. No deferred value may be supplied by an implementation fallback or ambient cloud configuration. Qualification reports record the actual manifest and its owner, and re-open an architecture boundary if the measured results require it.