PART 2: Tx-Rails for Security, Action and IIoT

The Local View

Tx-Rails — Underlay Integration Patterns

One-line summary: Tx-Rails is an underlay, not a replacement. Customer companies keep the front-ends they trust (their banking app, ERP, clinical system, procurement portal, comms platform) and bind Tx-Rails beneath as a continuous cryptographic audit layer. Today that binding happens through one real, built, verified, packaged integration path — hash-only attestation, with three deeper paths that now run and commit in our own estate as reference implementations rather than packaged products. This document describes what each path actually does and what it doesn’t. Two independent axes run through everything below: four integration Modes (A–D) decide how content reaches Tx-Rails; the four-rung Data Visibility Ladder, immediately after the Modes, decides who can read it once it does.

---

The underlay philosophy

The single most important positioning point: Tx-Rails does not ask customers to replace systems they already trust. That is the difference between an “underlay” pitch and a “blockchain” pitch.

A blockchain pitch says: “Migrate your data and your front-end onto our new platform.” The underlay pitch says: “Keep your platform. Bind us underneath. Every transaction your existing system commits also gets a cryptographic fingerprint, cross-checked and anchored — without changing how your users interact with your product.”

This is the only positioning that makes sense for regulated incumbents (banks, housing associations, hospitals, government agencies) who have spent decades and tens or hundreds of millions of pounds/dollars building front-ends their staff and customers understand. Asking them to throw that away is a non-starter. Asking them to add one small, well-scoped call to an underlay that gives them tamper-evident, cross-jurisdictionally-verifiable proof is a tractable conversation.

The auditor subsystem (ChubbyChecker) is what makes the underlay distinct from “just put it on a blockchain”. ChubbyChecker performs independent cross-checks per transaction/block, operated by parties independent from the BFT validators. Compromise detection is automatic: when the count of provably-compromised servers exceeds the BFT threshold f, ChubbyChecker raises an alert — it does not halt the platform, and a human triages. This is the load-bearing safety net no blockchain pitch can credibly offer.

---

From underlay to substrate — one engine, your pace

Two things we say can sound like opposites: “keep the systems you trust — we bind beneath as an audit underlay” and “compose your own business processes from our Atoms.” They are not opposites, and they are not two products. They are the same deterministic action engine seen at different depths of adoption — and you choose the depth, at your own pace.

Today that ladder has two real, fully-packaged rungs — the fuller menu once sketched here, including the “edge-mediated” (Mode C) and “write-mediated” (Mode D) rungs described in the roadmap section below, now also has its core mechanisms built, each as a reference implementation a customer’s own team adapts rather than a rung a customer can simply step onto:

1. Pure underlay — change nothing. Hash-only attestation. Your apps and screens are untouched; we faithfully anchor the cryptographic fingerprint of what they already commit. The Atom library runs behind the audit — as the schema ChubbyChecker validates against — and you never see it.
2. Substrate — compose with us. For greenfield builds, or customers who want deeper adoption, you author business processes from Atoms in the Overseer Design Studio and the Overseer enforces them. Here Tx-Rails is the application substrate, not just the audit floor.

The through-line: the same audited, deterministic action engine that records a fingerprint of what your existing systems already commit can also run new processes directly — when, and only when, you choose to compose them. The underlay is complete on its own; composing is an expansion you grow into, never a condition of entry. That is why “underlay” and “build on us” are one continuous offer rather than a contradiction.

---

Mode A — Hash-only attestation: what’s actually built

The original design for this platform sketched four integration modes, trading integration invasiveness for how much of the 37-field Transaction Metadata Trace (see below) lands without changes to the customer’s screens. Only the first of the four is a fully built, packaged path a customer can adopt today. A second (Mode D) now has its core mechanism built and verified too, as a reference implementation rather than a customer-ready product. This section documents what Mode A actually does; the next section is honest about where the other three — including Mode D’s real caveats — actually stand.

What changes in the customer’s system: the customer’s transaction commit path is extended to publish a cryptographic hash of each committed transaction to the Tx-Rails underlay, via a signed call carrying a verified tenant identity.

What Tx-Rails receives: the hash, plus the identity/block-position metadata needed to place it. Not the transaction body, not the parties, not the amounts, not the timestamps as authoritative inputs.

Guarantees Mode A provides:

• Tamper-evidence: “this hash was committed at this time” is provable later, by anyone, using a portable proof artifact and public cryptographic primitives — not a claim that requires trusting the Tx-Rails database or software.
• Forward-only audit trail: the customer can prove their own hash sequence matches what was actually anchored.
• Cross-jurisdictional verifiability: Merkle roots of block slabs are anchored to Hedera, so a third party in another jurisdiction can verify the hash sequence existed without trusting the customer or Tx-Rails.
• Durable evidence, not a single-validator dependency: the raw block data and transaction-location index a proof is built from are both independently archived (cmd/block-archiver), not held only on the validator’s own disk — and a proof can be located from the transaction’s own content hash, not only from an internal Tx-Rails record of where it landed.
• Choice of anchor, not lock-in to one: Hedera is the default, but the anchor submitter is chain-selectable, and a built, tested Ethereum path already exists alongside it — a deployment picks the anchor that fits its own risk/cost tradeoff rather than inheriting a single fixed choice.

Guarantees Mode A does NOT provide:

• Independent re-verification of transaction contents — ChubbyChecker cannot run cross-checks against data it doesn’t have. (Where re-verification is structurally possible at all — two independent parties each submitting a claim about the same event — it’s Regime C’s bilateral settlement predicate that already provides it, not a Mode A/B/C/D gap; see below.)
• Detection of “the customer published a hash of a fake transaction body that they later substituted into their own system” — Mode A trusts the customer’s hash submission for what it represents.
• The full BFT cross-validation story: with only hashes, the BFT mesh has nothing semantic to validate.

When Mode A is appropriate:

• Customers in proof-of-existence regimes where merely showing “this record existed at this time” satisfies the regulatory requirement.
• High-volume / low-margin transaction streams where richer integration overhead would be prohibitive.
• Initial pilot phase before a customer commits to deeper integration — noting the deeper modes below, while their core mechanisms are built, aren’t packaged products a customer can simply install yet.
• Customers whose regulatory environment forbids transmitting transaction details to an external system at all — Mode A already satisfies this by construction, since it never receives them.

---

Roadmap: the deeper integration menu

The original design sketched three additional integration modes beyond Mode A. All three are now deployed in our own estate and committing through consensus (goldbftd + org-server-abci + org-gateway, plus a real Postgres for the two that need one). On 30 September 2026 a change made at the source of each produced a new attestation, committed and read back identically from two independent validators — Mode B at block 760822, Mode C at 760824, Mode D at 760826. That test matters because the gateway returns a success code and a real transaction id as soon as a submission passes admission control, and admission control runs neither the action’s validation nor the authorization check — so all three had previously been reported as working on evidence that proved nothing had committed. See below for exactly what each one covers and doesn’t. None is a packaged, install-and-go product; no customer has been onboarded through any of them yet. This document stays honest about that gap rather than presenting more than what’s actually there. Most customers will eventually want more than one mode running at once, per workflow. No customer has been onboarded through any mode, including Mode A: everything described here runs in our own estate against our own data. Mode A is the only one that is a packaged, adoptable product; the other three are reference implementations for a customer’s own team to adapt. Adopting one of B/C/D answers how content reaches Tx-Rails; it says nothing yet about who can read it once it arrives — that’s the separate Data Visibility Ladder, covered right after Mode D below.

Mode B — CDC / change-data-capture observer: deployed and committing

What changes in the customer’s system: nothing. cdc-observer attaches to the customer’s Postgres write-ahead log as a genuine logical-replication client and observes committed changes asynchronously, with no change to the customer’s application.

What’s built: a real Postgres logical-replication consumer (pglogrepl, decoding pgoutput directly — no Debezium/Kafka dependency), verified against a real Postgres with wal_level=logical. The WAL operation itself (INSERT/UPDATE/DELETE) maps directly onto the matching RequType value, so no per-table semantic-intent config is needed. Identity attribution uses one coarse service-account credential per customer deployment — real tenant boundary, but per-user attribution is lost — reusing the exact same static-token pattern Mode D’s outbox-relay already has, no new verifier code required. A mapping layer back to real identity from the customer’s own audit columns has no prior art anywhere in this codebase and remains unbuilt. Ships in connectrpc/services/org-gateway/cmd/cdc-observer.

Forensic, not preventative: the customer’s transaction is already committed to their own database by the time this mode observes it via CDC — it detects and proves a problem after the fact, never blocks it in flight.

Where it fits: large enterprises whose systems genuinely cannot be modified (frozen vendor packages, regulatory-frozen code, end-of-life systems still processing material volume), and customers who can’t tolerate any commit-path latency at all — once a customer actually adopts the reference implementation.

Mode C — Gateway-mediated: deployed and committing

What changes in the customer’s system: application traffic routed through edge-gateway at the network edge, deriving attribution from a JWT and semantic intent from an explicit route config — the application itself unmodified.

What’s built: a real inline HTTP reverse proxy, not the fragile heuristic REST-inference engine early sketches worried this mode would need — semantic inference from arbitrary REST shapes doesn’t generalize across customers’ API conventions, so this reference implementation uses an explicit per-customer route-mapping config (method + path prefix → atom) instead. It reuses org-gateway’s existing JWT verification entirely — edge-gateway never inspects a credential itself, only forwards it through, so no new auth code was needed. It sits inline in the customer’s live production traffic, a materially different reliability commitment than an out-of-band audit sidecar — an outage there breaks the customer’s application, not just their audit trail. Ships in connectrpc/services/org-gateway/cmd/edge-gateway, verified end-to-end including the fail-closed case (an unauthenticated request is blocked before ever reaching the backend).

What it adds over Mode B: deterministic JWT-derived attribution (no dependency on the customer’s tables carrying audit columns), and — because it sits inline — genuine preventative rejection: fail-closed, unconditionally, by design. This is the one of the three that can actually refuse a bad transaction before it reaches the customer’s backend; Mode D’s shipped outbox variant explicitly cannot.

Where it fits: customers with a single, clean externally-exposed API edge, and high-value flows where JWT-derived attribution matters but the application code itself can’t be touched — once a customer actually adopts the reference implementation.

Mode D — SDK / atomic dual-write: deployed and committing

What changes in the customer’s system: the application calls Tx-Rails alongside its own database write, with explicit semantic-intent tagging (REVERSAL / CORRECTION / RESTATEMENT vs ordinary CREATE / UPDATE / DELETE — all real RequType values now, not a sketch).

What’s built: this is the cleanest of the three from a trust-model standpoint — the customer’s own authenticated session makes the call directly, no inference, no identity-federation problem. True cross-system atomicity is a hard distributed-systems problem in practice; the realistic version, and the one that’s built, is an outbox pattern (write intent locally, relay asynchronously) — eventually-consistent, not literally atomic. org-gateway‘s ExecuteAction accepts a client-supplied idempotency key and derives a deterministic transaction id from it, so a crashed or retried relay never double-applies the customer’s write — verified end-to-end against a real goldbftd + org-server-abci + org-gateway stack, including the case where CometBFT’s own mempool rejects an exact-duplicate retry outright before it ever reaches the application layer. A reference outbox-relay implementation (Postgres-backed store, Connect-RPC client, a runnable poller) ships in connectrpc/services/org-gateway/cmd/dualwrite-relay.

What’s still missing: packaged, documented client libraries beyond the reference Go implementation — the generated Connect stubs mean any language can call the gateway directly, but there’s no polished multi-language SDK yet — and no customer has been onboarded through this path. Not yet a product a customer can simply install; a reference a customer’s own team adapts to their own outbox table.

What it provides now: the full transaction payload and explicit semantic intent — fine-grained REVERSAL/CORRECTION/RESTATEMENT distinctions that no inference layer could recover after the fact. Independent content re-verification is a different question this doesn’t answer: for a single submitter there’s no independent fact to check a claim against, so Mode D’s content delivery doesn’t unlock re-verification the way it unlocks semantic-intent tagging. Where genuine re-verification is possible — two independent parties each submitting a claim about the same event — that’s Regime C’s bilateral predicate, a different mechanism entirely.

Where it fits: high-value flows where explicit application-decided semantic-intent tagging matters for regulatory purposes (settlement reversal semantics, financial-correction audit, restatement of regulatory submissions) — once a customer actually adopts the reference implementation. Not a fit for independently re-deriving single-party claims like balance sufficiency or KYC status — Tx-Rails has no independent fact to check those against regardless of which mode delivers the content; genuinely multi-party checks (authorisation chains, counterparty agreement) are Regime C’s domain, not Mode D’s.

If and when any of the three become packaged, install-and-go products, this document will describe them that way — the same standard applied here for each one’s core mechanism.

---

The Data Visibility Ladder — four rungs, independent of which Mode you pick

The four Modes above answer how content reaches Tx-Rails at all — nothing, a WAL observer, a gateway, or a direct SDK call. A separate question, orthogonal to all four, is who can actually read whatever content does arrive once one of them is sending it. That’s the Data Visibility Ladder: four rungs, each an explicit answer to “who can decrypt this field, and what does the platform give up or gain in exchange.” A customer climbs the rung that matches their own risk tolerance against how much platform-side service — cross-checking, referential validation, independent audit — they want in return. The full design lives in structured-atom-privacy-ladder-design.md; this section is the customer-facing summary, kept in sync with it.

Rung	Who can decrypt	What the platform gives up	Status
1 — Plaintext	Everyone in Tx-Rails’ own operational chain	Nothing — full validation, full ChubbyChecker cross-checking	Default today, for every content-receiving Mode (B, C, D), once adopted
2 — Platform-key encrypted	Tx-Rails (customer explicitly consents)	Nothing structurally — the platform can always decrypt to validate/cross-check, same as plaintext, just protected from anyone outside the platform’s own key custody (a stolen DB backup, a network intercept)	Mechanism built, carrying no production data. Ten fields of every transaction record are already sealed individually by it, each under its own per-record data key bound to the record and field it belongs to: the client node, the signing string, the user and role, the amount mantissas and exponents, and the database, schema, table and record identifiers. That last group matters more than it looks — a pointer to the exact customer row a transaction touched is a de-anonymisation index if left in the clear, whatever else is protected. The sealer and its schema exist and are exercised by tests, and organisations.tenant_sealed_fields is present in the live schema — but measured 2026-10-02 it held zero rows, against 33,964 rows in trace.slab_anchors on the same tier. No record has been sealed in a running deployment. This is the intended floor for the content-receiving Modes and the current direction of travel, not a capability available today.
3 — Customer-key encrypted	Only the customer — Tx-Rails genuinely cannot decrypt, even in principle	Depends on the field — nothing, if the platform never validated that field’s content anyway; the rest of the cross-check catalogue, for the narrower case where we are expected to validate data only the customer can read	Already solved today for fields Tx-Rails never validates. Genuinely open only for the narrower case where we are expected to validate customer key-encrypted data.
4 — Partner-key encrypted	Only a named third party the customer chooses (a manufacturing partner, a regulator) — asymmetric, multi-recipient	N/A — separate key-management machinery layered on top of Rung 3	Undesigned. No code anywhere.

Rung 1 — Plaintext: what every content-receiving Mode ships with today

Whatever structured content a customer’s chosen Mode (B, C, or D) delivers, it arrives unencrypted, and Tx-Rails’ own validators read it directly — the same fields our referential-integrity and cross-field checks already parse. This is where every real deployment sits today: Mode A never receives content at all (stricter than even this rung — see “Why Mode A is the most private option” below), and none of B/C/D has shipped a visibility control yet. Full ChubbyChecker checking is available at this rung by construction, since nothing is hidden from the validators those checks run against.

Rung 2 — Platform-key encrypted: concretely scoped, not yet wired

The customer explicitly consents to Tx-Rails being able to read a field, in exchange for the platform keeping the ability to independently verify it. The concrete, scoped use case is amounts-constancy checking — proving a business record’s numeric values didn’t silently change between submission and recording, a check cc029‘s own amount-field-consistency logic already performs today, in plaintext. The design: encrypt one generic positional array (mantissa/exponent big-int pairs, no field names — the same shape the Trace’s own int64Amounts/int32Exponents already use) under Tx-Rails’ own key immediately after it’s copied from the source record, then decrypt both the pre- and post-submission arrays to compare plaintext values — never comparing ciphertext directly, since AEAD’s fresh-nonce-per-encryption means an unchanged value never re-encrypts to the same bytes twice. This reuses the Encryptor/KeyProvider mechanics already live for the ten Trace fields the sealer covers (ClientNodeID, TxSignStr, UserID, RoleID, Int64Amounts, Int32Exponents, and the Database, Schema, Table and RecordID row pointers — counted from the sealing code itself, 1 October 2026; this page previously said six, which predated the four row-pointer fields) — extended to one more generic array, not a new system. Since the independent constancy check should run inside ChubbyChecker rather than the validator itself — that’s the entire point of an independent auditor — chubbychecker-joint now has its own KeyProvider/Vault wiring (2026-08-17, mirroring org-server-abci‘s construction exactly), and the constancy check itself is built on top of it: cc-bpd-038 compares the raw, consensus-agreed submitted amounts against the decrypted, quorum-verified persisted amounts across every configured replica, positionally. Verified end-to-end against a real single-node goldbftd + org-server-abci + chubbychecker-joint stack plus a real Vault dev-mode container, both directions: a genuinely-committed, genuinely-encrypted transaction’s amounts matched cleanly (no finding); the same persisted row, then directly corrupted, was correctly caught as CatastrophicFailure once chubbychecker-joint rechecked that block height. Full design: structured-atom-privacy-ladder-design.md, Rung 2.

Rung 3 — Customer-key encrypted: solved for one case, genuinely hard for another

Tx-Rails genuinely cannot decrypt — not “chooses not to,” structurally cannot. This splits cleanly into two cases. Fields the platform never validates — free text nobody cross-checks — are already solvable today, with zero new engineering: store the value as a blob addressed by its own content hash, exactly the way content-store already handles bulk attachments (documents, images, scans) under Mode D, and put only the hash in the atom’s payload. This is Rung 1’s own opaque-reference pattern applied to a structured field’s free text, not a new capability — it’s why Mode D’s bulk-attachment path can honestly claim genuine customer-key encryption today, with zero platform code changes, since content-store never parses what it stores. Fields the platform structurally needs to read — a foreign-key check like requireCoAAccountExists, a cross-field consistency check, a typed column another table’s constraints depend on — are where the real tension lives: the platform cannot validate a value it cannot see, so if it can decrypt to validate, this rung’s core property no longer holds for that field. This narrower case is a real ~6–9 month build (struct-tag classification, a customer-supplied-KEK KeyProvider, ChubbyChecker cross-checks that shift from validating content to validating ciphertext/AEAD-tag integrity, mirroring the shift the already-encrypted Trace fields already require of any consumer) — scoped per-field, per-atom, once a real customer need names the specific field, not a platform-wide rollout.

Rung 4 — Partner-key encrypted: undesigned

The customer encrypts for a named third party’s public key — a manufacturing partner, a regulator, a downstream counterparty — not for themselves. See “Sharing content with manufacturing partners” below for the sketch. This is a different key-management model (asymmetric, multi-recipient) layered on top of whichever of Rungs 2 or 3 it applies to, not a variant of either — building Rung 2 or Rung 3 does not get this rung for free, since it’s separate key-management machinery. Nothing exists in code for this today.

Where each Mode sits on the ladder today: Mode A is stricter than Rung 1 by construction — it never sends content at all, so there’s nothing to encrypt or leak in the first place. Modes B, C, and D — once a customer adopts one — all ship at Rung 1 for structured fields; Rung 2 is concretely scoped but not yet wired into any of them; Rungs 3 and 4 remain undesigned for structured fields specifically. The one standing exception is Mode D’s bulk-attachment path through content-store, which already delivers Rung-3-equivalent privacy today for documents and images — just not for the structured fields sitting alongside them in the same Trace.

---

The Transaction Metadata Trace contract — what Tx-Rails actually sees

Every transaction processed by Tx-Rails generates a Trace record under a fixed, design-frozen 37-field schema — the substrate ChubbyChecker’s cross-checks run against. The schema does not vary by customer, deployment, or integration mode: every transaction across the platform produces a Trace of exactly this shape, which is what makes the contract auditable by a technical reviewer independent of which integration mode a given customer uses.

What varies by mode is which of those 33 slots actually get filled. Under Mode A — the only mode that is a packaged, adoptable product, though no customer has been onboarded through it — only the identity/location-pointer, cryptographic-commitment, BFT-consensus, and operation-discriminator fields are populated (tenant boundary, transaction id, block/slab position, the hash itself, block id/height, op-code tags). The fields that would carry business content, quantitative facts, or semantic intent are, by design, empty: Tx-Rails never receives that content under Mode A. Each of the three reference implementations, once a customer adopts it, fills the rest — business content and explicit semantic intent (RequType) all flow through ExecuteActionRequest today — this is one fixed contract with mode-dependent fill, not four different schemas. Two of the 33 (isTower/counterIsTower, used for Regime C peer selection — see §4 of the Global View below) are newer additions at the proto level (CoreMeta fields 64/65, orgnodes-overseer@8e2e40f); the trace-store’s own Postgres schema carries both, though their value stays false/false today since nothing upstream sets CoreMeta‘s IsTower/CounterIsTower yet.

Channel	Visibility today (Mode A)	Purpose
Transaction Metadata Trace	Tx-Rails (always); ChubbyChecker auditors (always) — for the identity/crypto/BFT/discriminator fields that Mode A actually populates	The cryptographic envelope around the transaction — the substrate the ChubbyChecker checks run against
Content	Customer (always); Tx-Rails: never, under Mode A. Under the Mode D reference implementation, once a customer adopts it, Tx-Rails receives structured payload fields as sent — no field-level encryption or visibility controls yet for those. Bulk attachments (documents, images, scans) are the exception: routed through content-store, which never parses what it stores, so customer-key encryption for those is a real, working convention today, not undesigned — see the Mode D section above. Structured-field customer-key encryption remains undesigned regardless of mode.	The actual business payload — descriptions, party names, document attachments, free-text fields, anything strategic. Not sent to Tx-Rails today, under any circumstances.

The 33 fields, by category

Category	Fields	What they expose to Tx-Rails
Identity & location pointers (populated under Mode A)	federationId, counterFederationId, recordId, txId, sector, pyramid, counterSector, counterPyramid, entnum, counterEntnum, dataCentre, counterDataCentre, country, counterCountry, database, schema, table, clientNodeId, userId, roleId, isTower, counterIsTower	Opaque tokens — who, where, and which slot, in an externally-anonymous form. A user ID is a verified but opaque tenant marker, not a name. A table reference is the schema slot, not the business meaning. The mapping from token to human-readable identity stays on the customer side. isTower/counterIsTower are a routing flag pair (which of national-meta-federation vs national-aggregators is the Regime C peer), not identity in the same sense as the rest of this row — grouped here for lack of a better-fitting category.
Cryptographic commitments (populated under Mode A)	hash (sha256 digest), txSignStr, merkleRootHex	Pure cryptographic objects. No business meaning. The hash is a sha256 of the signing string, computed by us — it is not itself the Merkle leaf. The leaves this pipeline anchors are CometBFT block hashes, so an inclusion proof for one transaction reaches the anchored root through CometBFT’s own transaction and header trees rather than through this field. The signature establishes provenance; the Merkle root is the block-level commitment.
BFT consensus metadata (populated under Mode A)	blockId, slabId, blockHeight	Where the transaction lives in the ledger — block, slab (the block-group anchored to Hedera), height. Reveals nothing about content.
Operation discriminators (populated under Mode A)	opCodeExec, opCodeCommit, reqType	Tags identifying the kind of operation (commit / pre-commit / read / etc.) without exposing what the operation is about.
Quantitative facts (empty under Mode A — see below)	int64Amounts, int32Exponents	Numeric values, decoupled from unit and meaning, once a customer adopts a content-receiving mode (Mode D today). Tx-Rails would see that a transaction had value 12345 × 10⁻² — not whether that’s USD, GBP, tonnes of grain, hours of labour, or kilowatt-hours. Not sent at all under Mode A.

Why Mode A is the most private option, not the least

Because Tx-Rails never receives transaction content at all under Mode A, there is no leakage question to manage the way there would be for the content-receiving modes above. A Tx-Rails operator looking at a Mode A Trace sees only that some opaque, verified entity committed some operation at some block height, with cryptographic proofs attached — identity tokens, hashes, consensus housekeeping, and operation tags, none of which carry business meaning by construction. That’s not a current limitation to work around; it’s the actual privacy property Mode A is built to provide.

All three roadmap modes, now that all three are deployed and committing, already expose this gap concretely: any customer who adopts one of them sends Tx-Rails full, unencrypted structured content today (the fields our server-side validators parse and check referential integrity against — amounts, descriptions, party references), sitting at Rung 1 of the Data Visibility Ladder above. Each still needs its own move up that ladder for content-level visibility — starting with the amounts field, which is the one place any substantive information would leak, and even then only pseudonymously (the numeric value visible, the unit and meaning not). The one exception: Mode D’s bulk-attachment path (documents, images, scans — anything routed through content-store rather than a structured field) already sits at Rung 3 today, with zero platform code changes, since content-store never parses what it stores — see the Mode D section above.

Amounts specifically: one rung now concretely scoped

For customer audiences whose threat model would treat any quantitative leakage as a sovereignty breach — defence aviation, export-controlled goods, certain competitively-sensitive industries — the amounts field is the sharpest instance of the general Data Visibility Ladder above, since it’s the one place a content-receiving Mode currently exposes any substantive information at all. Today, once a customer adopts one of the three content-receiving reference implementations, amounts sit at Rung 1 (plaintext) like every other structured field. Rung 2 (platform-key encrypted) is the one concretely scoped beyond the sketch — see the Ladder section above for the full design, and structured-atom-privacy-ladder-design.md for the underlying detail. Rungs 3 and 4 remain undesigned for amounts specifically, for the same reason they’re undesigned generally: amounts are exactly the kind of field the platform structurally needs to read (constancy checks, conservation-of-amounts cross-checks), the harder case Rung 3 describes. The honest answer for a customer who needs true customer-key privacy on amounts specifically, today, is still “Mode A already gives you the strictest version of this for free, because we don’t receive amounts at all yet.”

What this means for ChubbyChecker

ChubbyChecker’s cross-checks operate on the Trace, not on the content — and today, on only the categories Mode A actually populates. They verify:

• Signature validity against the validator’s public key (cryptographic commitments category)
• Merkle inclusion of each transaction in the slab root anchored to Hedera (cryptographic commitments + BFT metadata)
• BFT quorum and proposer evidence at the relevant block height (BFT metadata)
• Operation-code sequence consistency (discriminators)
• Identity-token consistency across related transactions (identity pointers)
• Slab-anchor cross-references (BFT metadata + cryptographic commitments)

Checks that depend on quantitative facts — conservation of amounts across operation pairs that should balance, range checks, pattern checks — have nothing to run against under Mode A, since amounts are never sent. They activate once a customer adopts a content-receiving mode (Mode D today). None of the checks above need to see content to work today; integrity at the cryptographic and consensus level is fully provable without business-semantic visibility.

And the checks always have something deterministic to verify against: every atom executes from block-deterministic inputs only — the BFT-consensused block time (never a wall clock) and deterministic record IDs — so every replica re-derives byte-identical state from the same transaction stream. This is enforced in the codebase by an automated test that rejects any wall-clock use in atom code. It is the property that makes ChubbyChecker’s divergence detection meaningful: a state mismatch can only be a fault, never benign non-determinism.

Sharing content with manufacturing partners (roadmap)

This presumes Tx-Rails is receiving content — true for Mode D’s reference implementation today, still false under Mode A. It’s not built even for Mode D, though: the outbox-relay passes the raw payload straight through, with no partner-encryption mediation layer. The sketch, for when it applies: content destined for a manufacturing partner, regulator, or counterparty would use a customer-side asymmetric mechanism — the customer encrypts the content under the partner’s public key, and only the partner can decrypt. Tx-Rails would mediate the exchange by validating that the corresponding Trace is structurally consistent and cryptographically committed, without ever decrypting the content itself. The partner relationship and the integrity guarantee stay decoupled. Not available today.

---

FAQ — common customer-architect questions

These are the questions customer architects and technical-due-diligence reviewers tend to raise once they’ve absorbed the Mode A / roadmap distinction and the Kademlia overlay (see kademlia-edge-overlay.md). The answers below are the recommended canonical responses; adapt phrasing to the audience but do not deviate from the substance without checking back to memory.

Q1. Are your domain-specific actions completely redundant for a Mode A customer?

Short answer: Dormant for you, not redundant for the platform.

Long answer:

Tx-Rails ships with a large library of transaction-schema actions spanning many business domains — asset maintenance, banking, healthcare, housing, food and beverage, mining, manufacturing, energy, transport, real estate, pharmacies, construction, aviation, procurement, and a full finance/accounting domain (budget, chart of accounts, P&L+BS, accounts receivable, bank reconciliation, payroll, tax). Each one is the validation + persistence schema for a specific business event committed to the tx-rails BFT state machine.

A Mode A customer invokes exactly one of them: a generic HashAttestation action. The rest are dormant for that customer’s day-to-day operations. They are not removed from the platform because:

1. The breadth is itself a pitch asset. A large, mature action library demonstrates platform maturity to a CIO or investor evaluating fit, and shows the shape the substrate path can grow into.
2. They are the eventual upgrade path. A customer who starts in Mode A but later wants stronger audit guarantees can move to one of the roadmap modes, each now reachable via its own reference implementation, without a platform redesign. The schemas are already there, waiting on the ingestion side that connects to them.
3. Unused schemas have zero runtime cost. A validator that never receives a given action type never invokes its handler. The cost is container image size and codebase surface, not production compute or latency.

The honest framing for a Mode A customer: “Most of the platform’s schema depth is dormant for you today. You get the underlay capabilities — cryptographic anchoring, tamper-evidence, cross-jurisdictional verifiability — without any schema-integration cost. If you ever want stronger audit guarantees, the upgrade path is in place; it just isn’t built yet.”

Q2. Is Kubernetes a requirement for us as a customer?

Short answer: No.

Long answer:

The tx-rails platform infrastructure itself runs on Kubernetes (microk8s clusters for workload BFT validators and Patroni replicas) plus LXD (machine charms for the ChubbyChecker auditor mesh — the parallel orchestration stack reinforces the BFT-independence story). This is a deployment-side concern for the tx-rails operator; the customer does not deal with it directly.

The customer’s existing infrastructure is irrelevant to our K8s usage. The customer’s legacy front-ends and databases continue to run wherever they run today — mainframes, traditional VMs, hosted SaaS, the customer’s own container platform. Mode A asks the customer to add a hash-publish call to their commit path; this is a small library call, not an orchestration change.

The customer’s edge devices, if any participate in the Kademlia overlay, do so via libp2p, which is a library compiled into the device’s runtime (mobile, IoT, branch-server, point-of-sale). No containers, no Kubernetes required for that either.

The one forward-looking case where K8s becomes relevant on a customer’s side: if the customer later chooses to host their own tx-rails BFT validator or auditor node — analogous to a bank hosting its own SWIFT node rather than using a shared one — they would need K8s or LXD on their infrastructure to host the validator stack. This is optional, typically a Y2-Y3 conversation for customers with operational maturity to run a BFT node, and not part of an initial deployment.

In short: tx-rails has an opinion about its own deployment substrate (K8s + LXD). It has no opinion about the customer’s deployment substrate, and the customer is free to run anything they like.

Q3. If most of the action schemas are dormant for our Mode A integration, are we paying for unused complexity?

Short answer: No — the unused schemas have zero runtime cost to a Mode A customer.

Long answer:

The schemas exist in the validator container images, but a validator that never receives, say, a MaintenanceCostRecord action will never invoke its handler. There is no per-schema runtime cost; only the cost of the actions that actually flow through the system, which for a Mode A customer is HashAttestation and nothing else.

The cost of carrying the unused schemas is in container image size (megabytes) and developer cognitive load when reading the codebase, not in production runtime, throughput, latency, or compute spend. The customer is not paying for unused complexity in any operational sense.

Q4. Can we start in Mode A and migrate to a deeper mode later without a forklift upgrade?

Short answer: That’s the intent of the design — and it’s now a real path for all three deeper modes, each via its own reference implementation, not just a design intent.

Long answer:

The platform is architected so that a Mode A → Mode D migration, using Mode D’s now-built core mechanism, operationally looks like:

1. Identify which transactions in the customer’s legacy system the customer wants to dual-write to tx-rails.
2. Map each transaction type to a tx-rails action from the existing schema library (or, in the rare case the customer’s transaction type isn’t already modelled, write a new action — a one-day engineering task for a typical domain).
3. Add the tx-rails write to the customer’s commit path, via the outbox pattern Mode D actually ships with (the reference implementation in connectrpc/services/org-gateway/cmd/dualwrite-relay — see the roadmap section above).
4. Keep the Mode A hash-attestation in place for older transactions — historical data anchored in Mode A remains verifiable, while new transactions are mirrored fully via the newer mode.

The same shape applies to a future Mode A → Mode B (CDC, no commit-path change, an added stream subscriber) or Mode A → Mode C (a gateway added in front of the API edge, a DNS/load-balancer change) migration.

In all cases, the underlay infrastructure already deployed for Mode A would continue to operate unchanged — the migration is additive, not a replacement. All three modes’ core mechanisms are real today, though a migration still means a customer’s own team adapting a reference implementation (the outbox-relay, the edge-gateway route config, or the cdc-observer table mapping), not flipping a switch, and no customer has actually made any of these migrations yet. Say that plainly rather than implying any of this is a phone call away.

Q5. Does the Kademlia overlay add value if we never adopt a deeper mode?

Short answer: Partially, today — the overlay itself is a mix of built and roadmap, independent of which data-plane integration mode a customer runs.

Long answer:

Even a customer locked to Mode A can use the Kademlia overlay described in kademlia-edge-overlay.md — but be precise about what’s actually shipped versus sketched there, per that document’s own implementation-status table:

• Serverless peer discovery + JWT-gated stream auth — built and live today. Edge devices, branches, and partner-org nodes find each other without a central directory.
• Content-addressed verification (fetching a record and checking it against a published commitment) — roadmap, individually scoped against the security workplan.
• Pub/sub at the edge (gossipsub) — roadmap, same workplan track.
• Cross-org and cross-jurisdiction routing — partial: discovery works today; enterprise-CA identity and permissioned membership are roadmap.

For many customers in regulated verticals, peer discovery alone is a genuine capability their existing legacy stack doesn’t provide, at no additional integration cost — it piggy-backs on the same peer mesh the BFT validators use. The other three overlay capabilities are real, scoped, workplan-tracked direction, not currently live; don’t present them as available without checking that workplan’s current state first.

Q6. What if our edge devices can’t run libp2p (embedded, very low RAM, no networking flexibility)?

Short answer: A lightweight gateway pattern works — a libp2p-capable proxy device represents the embedded devices in the overlay.

Long answer:

libp2p requires a few megabytes of RAM, a TCP/IP stack, and the ability to maintain outbound connections. Most modern embedded devices (anything with an ARM Cortex-M4 or above) comfortably meet this. For genuinely constrained devices (older sensors, simple meters, single-purpose IoT with no spare memory), the standard pattern is:

1. Deploy a libp2p gateway device at the edge cluster — typically a branch-server or industrial PC.
2. Constrained devices speak whatever local protocol they speak (MQTT, Modbus, BLE, LoRaWAN, raw serial) to the gateway.
3. The gateway translates between local protocol and overlay primitives. It holds the device’s certificate or proxies on behalf of an authenticated upstream identity.

This is the same gateway pattern most IoT deployments already use for protocol translation — nothing unusual here. As with Q5, note that today the gateway rides on the peer-discovery layer that’s actually live; the enterprise-CA identity story it references is itself part of the roadmap, not shipped.

---

Edge cases that refine but do not invalidate the framework

Greenfield customers (no front-end to preserve)

The framework applies but the framing shifts. With no existing system to preserve, the pitch is not “underlay” (sit beneath what you have) but “substrate” (build your new system on top of us) — using the compose-with-Atoms path described above, not the deeper integration modes in the roadmap section, which are irrelevant here regardless of build status: greenfield customers have no existing write path to dual-write alongside in the first place.

Bulk-payload workloads (documents, multimedia, large signed PDFs) — core mechanism built

Relevant once a customer actually adopts Mode D’s reference implementation — Mode A never receives payload content, bulk or otherwise. CometBFT’s own transaction-size ceiling (~1MB, unmodified across this platform’s deployments) makes it structurally impossible for Mode D’s outbox-relay to carry bulk content through the chain directly, so it never does: a real, working content-store reference implementation (connectrpc/services/content-store) now exists, built and verified end-to-end against a real chain 2026-08-16. The deployment pattern is exactly the one this document originally sketched, now real rather than anticipated:

• Bulk content is uploaded once to content-store (content-addressed by its own SHA-256 hash — the server computes it, a caller can’t claim one that doesn’t match) — a local-filesystem-backed reference implementation today, same “reference, not packaged product” bar as Modes B/C/D themselves; a production deployment swaps in an S3-compatible backend via the same three-method Store interface, no other code changes needed
• Canonical transaction metadata + the content hash flows through Mode D’s atomic dual-write — no proto or outbox schema change needed at all: the existing HashAttestationAction atom (unmodified) already carries exactly a content_hash field, the same pattern Mode A itself uses
• The hash in the underlay binds the metadata to the content; content is independently retrievable and hash-verifiable from content-store at any later point

Verified concretely: a 3MB blob (well over CometBFT’s own ~1MB tx ceiling) uploaded to content-store, committed on-chain as a 64-byte hash reference via the unmodified HashAttestationAction, and independently retrieved back byte-for-byte with its hash re-verified. This is Mode D in spirit — the audit chain unbroken — handling bulk data efficiently. Like the rest of Mode D, this is a reference implementation a customer’s own team adapts, not a packaged product yet, and no customer has been onboarded through it.

Air-gapped / public-DLT-prohibited environments

Some regulated environments (defence, national-security, certain financial-services back-offices) prohibit anchoring any data — even Merkle roots — to a public distributed ledger like Hedera. Mode A still works within the customer’s own network in this case: hash attestation and BFT cross-validation are unaffected. What’s lost is the cross-jurisdictional verifiability story — a third party outside the customer’s network can’t check Hedera to verify anything, because nothing was anchored there. The audit chain becomes verifiable only by parties the customer admits to their own network. For most regulated commercial workloads, Hedera anchoring is permitted and the full cross-jurisdictional story holds.

Data sovereignty without public-DLT prohibition

A more common variant of the above: customers (especially government and critical-infrastructure) require the source-of-truth to remain in-jurisdiction. Mode A already satisfies this by construction — Tx-Rails never receives the transaction content at all, so there’s no content to keep in- or out-of-jurisdiction. Only the hash and the block-slab Merkle roots leave the customer’s control, and the latter go to Hedera by design. Mode D, now that it’s built, needs its own sovereignty answer for customers who adopt it — that’s future work, not a gap in Mode A today.

---

What this document is and is not

This document describes the integration pattern that’s actually built, and is explicit about what’s roadmap rather than reality. It is deliberately silent on:

• Specific protocol details (gRPC schemas, retry semantics, secret management)
• The BFT consensus implementation (CometBFT / goldbftd internals)
• The ChubbyChecker cross-check catalogue
• The Hedera anchoring cadence and cost model
• Per-vertical regulatory framings (covered in vertical-specific pitch documents)

For those, see underlay-integration-patterns.html for Mode A and the same honest roadmap framing, tx-rails-master-pitch.md for the cross-vertical narrative and financials, and the CLAUDE.md at repo root for the BFT architecture summary.

---

How to choose: a quick decision tree

1. Does “this record existed, unaltered, at this time” satisfy the audit requirement?

• Yes → Mode A is not just sufficient, it’s the right fit, today, as-is.
• No, independent content re-verification is required → check whether the claim is genuinely multi-party (two independent submitters whose claims must agree) or single-party. Genuinely multi-party: that’s Regime C’s bilateral predicate, already built. Single-party (e.g. “is this balance sufficient,” “is this KYC status current”): there’s no independent fact to check it against regardless of which mode delivers the content — say so plainly rather than implying a roadmap mode will eventually cover it. If inline rejection specifically is what’s needed, Mode C’s reference implementation provides it today, fail-closed by design.

1. Is explicit semantic-intent tagging (REVERSAL vs CORRECTION vs RESTATEMENT) a compliance requirement?

• Yes → this is Mode D territory specifically; the core mechanism (real RequType values, verified end-to-end) is built, but flag the reference-implementation caveat — it’s not a packaged product a customer installs, and no customer has been onboarded through it yet.
• No → Mode A’s proof-of-existence guarantee is enough.

1. Is public-DLT anchoring permitted in the customer’s regulatory environment?

• Yes → standard architecture, Merkle slab roots → Hedera.
• No → in-network anchoring only; document the cross-jurisdictional verifiability gap as a constraint. Mode A itself still works either way.

1. Is this a greenfield build?

• Yes → frame as “substrate”, compose with Atoms from day one.
• No → frame as “underlay”; Mode A today, be explicit that Modes B/C are roadmap and Mode D is a real but unpackaged reference implementation.

---

Why hash-only still holds up across verticals

Every customer scenario in every vertical can use Mode A today for exactly what it’s good at: proving a record existed, unaltered, at a specific time, verifiably by a third party who trusts nothing about Tx-Rails or the customer. Independent content re-verification isn’t something any of Modes B/C/D are missing — it’s only structurally possible where two independent parties each submit a claim about the same event, and that’s Regime C’s bilateral settlement predicate, not a gap in the integration modes. Explicit semantic-intent tagging is available now via Mode D’s reference implementation, but not through Mode A itself:

• Banking / FCA financial services: Mode A gives proof-of-existence and tamper-evidence for every payment / KYC event / suitability decision today. Balance sufficiency is a single-party claim — Tx-Rails has no independent fact to check it against regardless of which mode delivers the content, so this isn’t a gap to close. Authorisation chains that are genuinely multi-party (two independent parties’ claims must agree) are Regime C’s shape, not something Modes B/C/D need to add; inline rejection of fraud-flagged transactions at the API edge is available now via Mode C’s reference implementation, fail-closed by design.
• UK Social Housing (Awaab’s Law, Consumer Standards): Mode A gives tamper-evident, third-party-verifiable proof of repair tickets and tenant communications today — the audit-grade evidence is the compliance product even at this level. Full-payload content evidence is available via Mode D’s reference implementation now.
• NSW Health / TGA UDI / GS1 chain-of-custody: Mode A anchors every supply-chain event’s existence today. The bulk-data content variant for clinical documents is available now via Mode D’s content-store reference implementation (see above).
• Defence / national security supply chain: Mode A works today with the air-gapped refinement — in-network verifiability without Hedera anchoring.
• Frozen-vendor enterprise: Mode A is the right and sufficient starting point today; Mode B (CDC observer) is the natural next step via its reference implementation, for vendors whose application source can’t be touched.
• Greenfield regulated build: substrate framing (compose with Atoms) from day one — not the roadmap integration modes.
• Proof-of-existence regulatory regimes: Mode A is sufficient and cheapest, today, as-is.
• Customer with a clean API edge (new-deployment SaaS, government service-delivery program): Mode A works today; Mode C (gateway-mediated, deterministic JWT-based attribution, fail-closed inline rejection) is the natural upgrade via its reference implementation.

This is the right level of generality for an investor pitch and a customer technical conversation. Pitch the underlay philosophy first; be upfront that Mode A is the one real, fully-packaged integration path today; introduce Modes B, C, and D as real, verified core mechanisms that are each reference implementations, not packaged products yet.

---

What would stay true across all four rungs of the Data Visibility Ladder, once it’s fully wired

Today there’s nothing to choose — Mode A never sends amounts (or anything else) at all, so the question is moot and the answer is already stricter than any rung by default, at zero configuration cost. Mode D now receives content (unencrypted, at Rung 1), so the “nothing to choose” framing already doesn’t hold for Mode D adopters even though Rungs 2–4 remain mostly unwired. Once the higher rungs are actually wired in — for Mode D, or for Modes B/C once they exist — the design intends for this to hold regardless of which rung the customer picks:

• The other 31 of the 33 Trace fields are unaffected — identity tokens, cryptographic commitments, BFT metadata, and operation discriminators behave identically, exactly as they do under Mode A today.
• ChubbyChecker still runs the cryptographic-integrity checks (signature validity, Merkle inclusion, BFT quorum, slab anchoring), which are the load-bearing safety net — true today, under Mode A, already.
• The content channel splits in two: structured fields (descriptions, party names in plaintext, other validated payload fields) would move up the Data Visibility Ladder as each rung gets wired — Rung 1 is the only one live for structured fields today, for any mode. Documents/bulk attachments are different: Mode D’s content-store path already sits at Rung 3 today, zero platform changes needed, since content-store never parses what it stores. Under Mode A, no content of any kind is visible to Tx-Rails at all — not encrypted-and-withheld, simply never sent, which is stricter still than any rung.
• The Hedera slab-anchoring guarantee — cross-jurisdictional tamper-evidence via a public ledger — is intended to work identically whichever mode eventually gets built; it already works this way under Mode A.

The amount-visibility choice is purely about how much numeric information Tx-Rails sees for the cross-checks, once there’s numeric information for it to see at all — true today for Mode D adopters, unencrypted (Rung 1). Of the Data Visibility Ladder’s rungs, only Rung 2 (platform-key encrypted) is concretely scoped so far for amounts specifically (keeps that visibility, just protected against a storage breach or network intercept) — see the Data Visibility Ladder section above.

__________________