Files

Deploy to Phoenix / deploy (push) Has been cancelled

Details

- Config, docs, scripts, and backup manifests
- Submodule refs unchanged (m = modified content in submodules)

Made-with: Cursor

2026-03-02 11:37:34 -08:00

19 KiB

Raw Permalink Blame History

DBIS Rail Rulebook v1

Network: DBIS Mainnet (ChainID 138)
Document type: Operational and compliance policy
Companion document: DBIS Rail Technical Spec v1

1. Scope and Authority

1.1 Purpose

This Rulebook defines the operational and compliance rules governing the DBIS Rail on Chain 138. It establishes:

What constitutes good funds and under what conditions settlement is considered final.
How FundsStatus (ON_LEDGER_FINAL vs OFF_LEDGER_FINAL) is determined for each rail type.
The preconditions that must be satisfied before a Mint Authorization may be issued.
Reversal and exception handling before and after settlement.
Signer governance, revocation timing, and treatment of in-flight authorizations.
Incident and emergency controls, and audit and reporting standards.

The Rulebook does not define the technical implementation of the rail; that is set out in the DBIS Rail Technical Spec v1. This document governs the procedural and policy layer that underwrites the integrity of Mint Authorizations and the defensibility of settlement finality.

1.2 Authority and applicability

The Rulebook applies to all participants on the DBIS Rail, all signers contributing to Mint Authorizations, and all operators of the ISO Gateway and ledger domain that produce evidence for isoHash and accountingRef.
Amendments are governed by Section 9 (Versioning and Amendment Process).
In the event of conflict between this Rulebook and the Technical Spec, the Technical Spec governs on-chain behavior; this Rulebook governs operational and compliance obligations and the meaning of good funds and finality.

2. Good Funds Matrix

Settlement finality and the classification of funds as ON_LEDGER_FINAL or OFF_LEDGER_FINAL are determined by rail type and by the completion of defined operational triggers. The following matrix is authoritative for issuance of Mint Authorizations.

Rail type	ON_LEDGER_FINAL trigger	OFF_LEDGER_FINAL trigger	Reversal window
Wire (SWIFT/RTGS)	Core ledger posting complete and irrevocable per internal policy.	SWIFT (or equivalent) confirmation received and Nostro reconciliation complete per DBIS policy.	None after posting; reversals require separate corrective entry and must not be represented as the original settlement.
ACH	Settlement date reached and return/chargeback window has fully elapsed per applicable ACH rules.	N/A for typical ACH flows; if external rail is used, OFF_LEDGER_FINAL per reconciliation policy.	Duration of the return window; no Mint Authorization may be issued with ON_LEDGER_FINAL until the window has elapsed.
Instant rail	Receipt confirmation received and no recall or revocation flag present per rail operator rules.	N/A unless defined for a specific instant scheme.	Per the rules of the instant rail; Mint Authorization must not be issued before recall window has passed if applicable.
Cash	Vault receipt recorded and dual-control count completed and attested.	N/A.	None after count and attestation; discrepancies must be resolved before any Mint Authorization.
Internal transfer	Atomic ledger posting within the DBIS ledger domain completed.	N/A.	None; internal transfers are final upon posting.

2.1 Use of the matrix

The ISO Gateway and signers must not issue or sign a Mint Authorization unless the applicable trigger for the chosen FundsStatus has been met for the rail type in question.
OFF_LEDGER_FINAL may be used only where DBIS policy explicitly permits it for that rail and where external confirmation and reconciliation have been completed as defined in internal procedures.
Reversal windows must be respected; no Mint Authorization may assert finality for a rail type until any applicable reversal window has elapsed or has been explicitly waived by policy.

3. Accounting Sequence Requirements

3.1 Required sequence

Before any Mint Authorization may be issued:

Double-entry posting must be completed in the DBIS ledger domain for the underlying transaction (or batch) that the Mint Authorization will represent.
Reserve account tagging must be applied as required by DBIS policy (e.g., omnibus, segregated, or designated reserve accounts).
Accounting reference (accountingRef) must be produced in the deterministic form defined below and must be immutable once the posting is final.

No Mint Authorization may reference an accountingRef that does not correspond to a completed, compliant posting in the ledger domain.

3.2 Deterministic accountingRef structure

For auditability and reproducibility, the value placed in the Mint Authorization field accountingRef must be derived as follows:

accountingRef = keccak256(
  ledgerSystemId,
  journalId,
  batchNumber,
  postingTimestamp,
  reserveAccountId
)

Where:

ledgerSystemId identifies the ledger system (e.g., core banking or designated subsystem).
journalId is the unique identifier of the journal entry or batch.
batchNumber is the batch or sequence number applicable to the posting.
postingTimestamp is the time at which the posting was made final (e.g., Unix seconds or block-consistent value as defined by policy).
reserveAccountId identifies the reserve or settlement account(s) involved.

The exact encoding (e.g., ABI-packed bytes, ASCII concatenation) must be documented in operational procedures and must be consistent so that the same inputs always produce the same accountingRef. This allows external parties to verify that an on-chain accountingRef corresponds to a specific ledger posting.

3.3 Ordering and idempotency

Posting must occur before the Mint Authorization is signed and submitted.
Each accountingRef must correspond to at most one Mint Authorization (one-to-one) unless policy explicitly permits a defined exception (e.g., split instructions with a defined convention). Any such exception must be documented and auditable.

4. Mint Authorization Preconditions

A Mint Authorization (MintAuth) may be issued only when all of the following are satisfied. The Technical Spec defines the on-chain structure; this section defines the operational and compliance preconditions.

4.1 Good funds and finality

For the rail type and corridor in question, the applicable trigger from the Good Funds Matrix (Section 2) for the chosen FundsStatus (ON_LEDGER_FINAL or OFF_LEDGER_FINAL) must have been met.
No Mint Authorization may be issued with a FundsStatus that does not match the actual state of finality in the ledger or external rail.

4.2 Accounting

Double-entry posting must be complete and the accountingRef must have been computed per Section 3.2.
The accountingRef must be immutable (no further amendment to the underlying posting that would change the deterministic hash).

4.3 Compliance

All required compliance checks (KYC, AML, sanctions, jurisdiction, limits, and any corridor-specific rules) must have been completed with a clear pass.
No exception or override may be used unless explicitly permitted by DBIS policy and recorded for audit.

4.4 Evidence bundle and isoHash

The canonical ISO (or equivalent) evidence bundle that supports the settlement must be assembled and hashed to produce isoHash.
The evidence bundle must include at least: message type, identifiers (e.g., UETR, EndToEndId, instruction Id), amount, currency, parties, and timestamp consistent with finality. The exact schema must be documented in operational procedures.
isoHash in the Mint Authorization must equal the hash of this canonical bundle so that on-chain settlement is cryptographically tied to the off-chain evidence.

4.5 Signers

The authorization must be signed by a set of signers that satisfies the quorum rules defined in the Technical Spec (e.g., 3-of-5 with COMPLIANCE mandatory).
All signers must be allowlisted and effective at the time of signing (see Section 6).
Signers must not sign until all preconditions in Sections 4.1–4.4 are satisfied.

4.6 Time window and domain

notBefore and expiresAt must be set so that the authorization is valid only within an acceptable window (e.g., not more than 15 minutes from issuance, per Technical Spec recommendation).
chainId must be 138 and verifyingContract must be the DBIS SettlementRouter address. No Mint Authorization may be issued for another chain or contract.

5. Reversal and Exception Handling

5.1 Before Mint Authorization submission

If a reversal or exception is identified before the Mint Authorization has been submitted on-chain, no Mint Authorization may be issued for that settlement.
The ledger domain must be corrected (reversal entry, adjustment, or exception posting) as per standard accounting and compliance procedures. Any subsequent new settlement may result in a new, distinct Mint Authorization with a new messageId and accountingRef.

5.2 After Mint Authorization issuance but before on-chain submission or before expiry

If the underlying transaction is reversed or an exception is declared after the Mint Authorization has been signed but before it has been submitted on-chain, or before its expiresAt time:
- The Mint Authorization must be treated as invalid and must not be submitted.
- Signers or the ISO Gateway must revoke or withhold the authorization. Procedures must ensure that such authorizations are not submitted later by mistake.

5.3 After mint execution on-chain

Once the SettlementRouter has accepted the Mint Authorization and the GRU Mint Controller has executed the mint, the on-chain settlement is final from the perspective of the rail contracts.
Reversals or corrections in the fiat/ledger domain do not automatically reverse on-chain mints. Any corrective action (e.g., burn, offset, or recall) must be governed by a separate policy:
- Burn or offset: Where policy requires that a mistaken or reversed settlement be corrected, the designated process (e.g., burn of GRU or offsetting journal entry and burn) must be executed in accordance with DBIS procedures and, where applicable, with a new authorization or admin process.
- The Rulebook does not define the technical burn path; the Technical Spec and operational procedures must specify how burns or offsets are authorized and executed.
Disputes must be handled per Section 5.4 and incident procedures.

5.4 Disputes and exceptions

Participants must report disputes or exceptions in accordance with DBIS incident and dispute procedures.
No Mint Authorization may be issued for a transaction that is under dispute or exception until the dispute or exception is resolved and good funds are re-established per the Good Funds Matrix.
Post-mint disputes do not invalidate the on-chain settlement; they trigger the corrective and dispute-resolution procedures defined by DBIS policy.

6. Signer Governance and Revocation Timing

6.1 Signer roles and quorum

Signers are classified by category (e.g., OPS, COMPLIANCE, CUSTODY, RISK, AUDITOR) as defined in the Technical Spec.
The default quorum is 3-of-5, with COMPLIANCE mandatory. No Mint Authorization may be issued or submitted unless the signer set satisfies the quorum and category rules in effect at the time of submission.

6.2 Effective and revoked block semantics (recommended for v1.5+)

To avoid timing exploits, DBIS should maintain for each signer:
- Effective-from block (or time): The signer’s signature is valid only for Mint Authorizations submitted on-chain at or after this block (or equivalent time).
- Revoked-at block (or time): The signer’s signature is not valid for Mint Authorizations submitted on-chain at or after this block (or equivalent time).
The SettlementRouter (or supporting logic) should accept a signature only if, at the block at which submitMintAuth is executed, the signer is within the effective window and not yet revoked.
Until such block-based (or time-based) checks are implemented on-chain, operational procedures must ensure that:
- No Mint Authorization signed by a signer after the decision to revoke is submitted.
- Any in-flight authorization signed before revocation is either submitted before the revocation takes effect or is cancelled and not submitted.

6.3 In-flight authorizations

When a signer is revoked or suspended, any Mint Authorization that has been signed by that signer but not yet submitted must be treated as follows:
- If the remaining signers still satisfy the quorum and category rules, the authorization may be submitted only if policy permits and only before the signer’s revocation is effective on-chain.
- If the remaining signers no longer satisfy the quorum, the authorization must not be submitted; a new authorization with a new signer set must be produced if the settlement is still valid.

6.4 Compromised signer procedure

If a signer key is suspected or confirmed compromised, SIGNER_ADMIN must revoke the signer immediately via the SignerRegistry.
All in-flight Mint Authorizations that relied on that signer must be re-evaluated per Section 6.3. Any authorization not yet submitted that no longer meets quorum must not be submitted.
Incident reporting and key rotation procedures must be followed as per DBIS security policy.

7. Incident and Emergency Controls

7.1 Router pause

ROUTER_ADMIN may pause the SettlementRouter. When paused, no new Mint Authorizations may be submitted or executed.
Pause should be used in the event of a security incident, suspected compromise, or operational emergency that requires a halt to settlement execution.
Procedures must define who may request pause, who may execute it, and the process for resumption (including any required sign-offs or audits).

7.2 Mint controller pause

ROUTER_ADMIN (or the role designated in the Technical Spec) may pause the GRU Mint Controller. When paused, the SettlementRouter may still accept and record Mint Authorizations, but mints will not be executed until the controller is unpaused.
Use when mint execution must be halted but settlement recording or diagnosis must continue.

7.3 Participant suspension

PARTICIPANT_ADMIN may set a participant’s status to SUSPENDED or REVOKED. Suspended participants’ operational wallets must not receive new mints until the participant is reinstated; the SettlementRouter and ParticipantRegistry enforce this per the Technical Spec.
Suspension is appropriate when a participant is under investigation, in breach of terms, or poses a compliance or operational risk. Reinstatement must follow defined procedures.

7.4 Signer revocation

SIGNER_ADMIN may remove a signer from the allowlist. Revocation is effective as per Section 6; no new Mint Authorizations may rely on that signer once revocation is effective.
Used for routine rotation, suspected compromise, or disciplinary action. Procedures must document the effect on in-flight authorizations (Section 6.3).

7.5 Corridor or product suspension

Where the Technical Spec or supporting contracts allow corridor-specific or product-specific caps or suspension, ROUTER_ADMIN (or designated role) may suspend a corridor or product to halt new settlements in that segment while investigation or remediation is performed.
Procedures must define escalation and resumption.

7.6 Coordination and communication

Incident response procedures must define how pause, suspension, and revocation decisions are communicated to participants, signers, and operators, and how status is restored after the incident is resolved.

8. Audit and Reporting Standards

8.1 Required mappings

The following mappings must be maintained and be available for audit and regulatory examination:

messageId ↔ ISO evidence bundle: For each Mint Authorization submitted (whether accepted or rejected), the messageId must be linked to the full ISO (or equivalent) evidence bundle whose hash is isoHash.
messageId ↔ accountingRef: Each messageId must be linked to the accountingRef and thus to the ledger posting(s) that represent the underlying settlement.
accountingRef ↔ ledger postings: Each accountingRef must be traceable to the exact journal/batch and reserve account(s) in the ledger domain, using the deterministic construction in Section 3.2.

8.2 Retention

Evidence bundles, ledger postings, and the mappings above must be retained for the period required by applicable law and regulation and by DBIS policy (e.g., minimum seven years or as specified for financial records).
On-chain events (SettlementRecorded, MintExecuted, MessageIdConsumed, and related) are immutable; off-chain records must be retained and protected to support the same retention and accessibility requirements.

8.3 Reconciliation

Reconciliation between ledger domain, ISO Gateway state, and on-chain settlement state must be performed at the frequency defined by DBIS policy (e.g., daily or real-time for high-value corridors).
Discrepancies must be escalated and resolved per incident and exception procedures; no Mint Authorization may be issued against unreconciled or disputed positions unless explicitly permitted by policy and documented.

8.4 Reporting extracts

DBIS must be able to produce camt-like or equivalent extracts for:
- Completed settlements (by period, corridor, participant).
- Rejected or failed authorizations (with reason where available).
- Signer additions, removals, and quorum changes.
- Participant status changes (registration, suspension, revocation).
Such extracts support regulatory reporting, internal control, and counterparty due diligence.

9. Versioning and Amendment Process

9.1 Version identification

This document is the DBIS Rail Rulebook v1. Subsequent versions must be clearly versioned (e.g., v1.1, v2) and dated.
The effective date of each version must be stated in the document or in a companion change log.

9.2 Amendment authority

Amendments to the Rulebook are approved by the governance body or process designated by DBIS (e.g., board, risk committee, or delegated policy owner). The Technical Spec remains the authority for on-chain behavior; the Rulebook may be updated to reflect new operational or compliance requirements without necessarily changing contracts.

9.3 Effective date of amendments

Each amendment must specify its effective date. Until that date, the previous version of the affected sections remains in force.
Operational procedures (e.g., ISO Gateway configuration, signer training, participant communications) must be updated to align with the new version before the effective date, where possible.
If an amendment affects the interpretation of FundsStatus, accountingRef, or Mint Authorization preconditions, signers and the ISO Gateway must not issue or sign authorizations under the new interpretation before the effective date.

9.4 Publication and accessibility

The current Rulebook must be published in a location accessible to participants, signers, and auditors (e.g., docs/dbis-rail/ or an official policy repository). Superseded versions should be retained for audit and reference.

Document control

Field	Value
Title	DBIS Rail Rulebook v1
Network	DBIS Mainnet (ChainID 138)
Companion	DBIS Rail Technical Spec v1
Version	1
Status	Active

19 KiB Raw Permalink Blame History Unescape Escape