proxmox/docs/dbis-rail/DBIS_RAIL_LEDGER_ATTESTATION_ADDON_V1_5.md

DBIS Rail Ledger Attestation Add-On v1.5

Network: DBIS Mainnet (ChainID 138)
Document type: v1.5 Add-on — LPA state machine, reversal policy matrix, signer effective/revoked block enforcement
Companion documents: DBIS Rail Technical Spec v1, DBIS Rail Rulebook v1

---

1. Purpose and Scope

This add-on defines:

• The LPA (Ledger Posting Authorization / attestation) state machine so that settlement and reversals have deterministic operational outcomes.
• The Reversal Policy Matrix for before-mint and after-mint scenarios (invalidate, offset, burn, dispute).
• Mandatory signer effective-from and revoked-at block semantics so that authorization correctness is enforced on-chain under governance churn.

These extensions make outcomes rule-governed and examiner-credible. They implement the Rulebook’s “recommended for v1.5+” signer timing (Rulebook §6.2) as mandatory.

---

2. LPA State Machine

2.1 States

A Ledger Posting Authorization (LPA) is the ledger-domain object that backs a settlement and, when final, may support issuance of a Mint Authorization. Each LPA has a state from the following set:

State	Description
POSTED_FINAL	Posting is final and compliant; a Mint Authorization may be issued for this LPA provided all other preconditions (Rulebook §4) are met.
POSTED_ADJUSTMENT	An adjustment has been applied to the posting; no new Mint Authorization may reference this LPA until it is resolved (e.g. back to POSTED_FINAL or moved to POSTED_REVERSAL).
POSTED_REVERSAL	The posting has been reversed in the ledger domain; no Mint Authorization may be issued. If a Mint Authorization was already issued and executed, corrective action follows the Reversal Policy Matrix (Section 3).
DISPUTED_HOLD	The posting or settlement is under dispute; no Mint Authorization may be issued and no corrective burn/offset may be executed until the dispute is resolved and state is updated.

2.2 Allowed Transitions

• POSTED_FINAL → POSTED_ADJUSTMENT: Ledger/ops (e.g. correction, reclassification).
• POSTED_FINAL → POSTED_REVERSAL: Ledger/ops (reversal entry).
• POSTED_FINAL → DISPUTED_HOLD: Dispute procedure (designated role).
• POSTED_ADJUSTMENT → POSTED_FINAL: Ledger/ops (adjustment complete).
• POSTED_ADJUSTMENT → POSTED_REVERSAL: Ledger/ops.
• POSTED_ADJUSTMENT → DISPUTED_HOLD: Dispute procedure.
• DISPUTED_HOLD → POSTED_FINAL, POSTED_ADJUSTMENT, or POSTED_REVERSAL: Per dispute resolution outcome (designated role).

POSTED_REVERSAL and DISPUTED_HOLD are terminal for “may issue MintAuth”; only POSTED_FINAL (and per policy POSTED_ADJUSTMENT once resolved to POSTED_FINAL) permits issuance.

2.3 Link to Mint Authorization

• A Mint Authorization may be issued only when the underlying LPA is in a state that permits settlement (e.g. POSTED_FINAL).
• The ISO Gateway and signers must not issue or sign a Mint Authorization for an LPA in POSTED_ADJUSTMENT, POSTED_REVERSAL, or DISPUTED_HOLD.
• Operational procedures must record the LPA identifier (e.g. lpaId or equivalent) and state at the time of MintAuth issuance for audit.

---

3. Reversal Policy Matrix

3.1 Before Mint (Mint Authorization not yet submitted or not yet executed)

Scenario	Action
Reversal or exception identified before Mint Authorization is submitted	Invalidate Mint Authorization. Do not submit. Correct the ledger domain per Rulebook §5.1 (reversal entry, adjustment, or exception posting). Any subsequent valid settlement may result in a new Mint Authorization with a new messageId and accountingRef.
Reversal after Mint Authorization signed but before on-chain submission or before expiry	Treat Mint Authorization as invalid. Do not submit. Withhold or revoke the authorization per Rulebook §5.2. Procedures must ensure it is not submitted later.

3.2 After Mint (Mint executed on-chain)

Once the SettlementRouter has accepted the Mint Authorization and the GRU Mint Controller has executed the mint, on-chain settlement is final from the rail’s perspective. Reversals in the fiat/ledger domain do not automatically reverse the mint. Corrective action is governed by the following matrix:

Priority	Corrective action	When to use
Primary	Ledger offset + future corridor restriction	Standard reversal; offset the on-chain mint in the ledger domain and restrict the counterparty or corridor for future settlements per DBIS procedures. Documented in operational runbook.
Secondary	Burn (if token custody permits)	Where policy requires reduction of on-chain supply; burn of GRU per Rulebook §5.3 and Technical Spec / operational procedures. Requires appropriate authorization (e.g. ROUTER_ADMIN or designated burn path).
Tertiary	Debt/claim ledger entry + dispute handling	When offset or burn is not immediately applicable; record a debt or claim in the ledger domain and follow dispute-resolution procedures. Runbook reference for dispute handling and eventual resolution (e.g. future offset or burn).

Operational procedures must define who may initiate each corrective action, required sign-offs, and how the choice of primary vs secondary vs tertiary is made and recorded.

---

4. Signer Governance Timing (Mandatory for v1.5)

4.1 SignerRegistry Extensions

The DBIS_SignerRegistry (Technical Spec §6.3) must be extended for v1.5 with per-signer block semantics:

• effectiveFromBlock (uint256): The signer’s signature is valid only for Mint Authorizations submitted on-chain at a block number greater than or equal to this value.
• revokedAtBlock (uint256): The signer’s signature is not valid for Mint Authorizations submitted on-chain at a block number greater than or equal to this value. Use a sentinel (e.g. type(uint256).max) to indicate “not revoked.”

Initial semantics when a signer is added: set effectiveFromBlock to the current block (or deployment block); set revokedAtBlock to the “never” sentinel until revocation.

4.2 SettlementRouter Validation

At the block at which submitMintAuth is executed, the SettlementRouter must validate for each recovered signer:

• block.number >= signer.effectiveFromBlock
• block.number < signer.revokedAtBlock (or equivalent “not revoked” check)

If any signer is outside the effective window or is revoked at the current block, the transaction must revert.

4.3 Runbook References

• Emergency revoke sequence: SIGNER_ADMIN calls SignerRegistry to set revokedAtBlock = block.number (or next block) for the compromised or retired signer. In-flight Mint Authorizations that rely on that signer must not be submitted after the revocation block (Rulebook §6.3, §6.4).
• Key compromise drill: Follow DBIS security policy: revoke signer immediately, re-evaluate in-flight authorizations, incident reporting, key rotation. See Rulebook §6.4.

---

5. Cross-References

• Rulebook §3.2 — Deterministic accountingRef; LPA and accountingRef must align so that one accountingRef corresponds to at most one LPA/MintAuth unless a documented exception exists.
• Rulebook §5 — Reversal and exception handling; this add-on’s Reversal Policy Matrix operationalizes Rulebook §5.1–5.3.
• Rulebook §6.2 — Effective and revoked block semantics (“recommended for v1.5+”) are now mandatory in this add-on.
• Technical Spec §6.3 — DBIS_SignerRegistry; add effectiveFromBlock and revokedAtBlock state and accessors.
• Technical Spec §6.4 — DBIS_SettlementRouter; add validation that each recovered signer is active at block.number per Section 4.2 above.
• Hash Canonicalization add-on — LPA schema and lpaId (or equivalent) hash for attestation; see DBIS_RAIL_HASH_CANONICALIZATION_AND_TEST_VECTORS_V1_5.md.

---

6. Document Control

Field	Value
Title	DBIS Rail Ledger Attestation Add-On v1.5
Version	1.5
Status	Active