Touli Docs

Appearance

Touli Blockchain Anchoring Architecture (DLD) ​

Purpose ​

Define the anchoring subsystem for immutable proofing of off-chain economic events while preserving privacy and deletion rights.

Principles ​

  1. Off-chain ledger is source of truth; chain is proof layer.
  2. No PII on-chain.
  3. Anchoring is asynchronous and cannot block points credit.
  4. Erasure requests must break relinkability to on-chain proofs.

Anchoring Scope ​

Anchored events:

  • finalized points credit/debit ledger events
  • correction/reversal events
  • optional campaign-level aggregate events

Not anchored:

  • raw evidence payloads
  • model outputs with personal context
  • account profile data

Proof Payload Model ​

Per event leaf preimage (logical):

  • rotating_subject_id
  • ledger_entry_id
  • event_type
  • points_delta
  • occurred_at
  • config_snapshot_id
  • salt_version

Leaf hash:

  • leaf_hash = H(preimage)

Batch root:

  • Merkle root generated from ordered leaf set for batch window.

Pseudonymization and Unlinkability ​

  • Use rotating pseudonymous subject ids that are mapped off-chain.
  • Rotation schedule and key custody are controlled in secured data zone.
  • On erasure:
    • delete off-chain mapping keys
    • preserve chain root and leaf hashes (now non-linkable)

Batch Lifecycle ​

mermaid
flowchart LR
  ledgerFinalized[LedgerFinalizedEvent] --> leafStage[StageLeafRecord]
  leafStage --> batchWindow[OpenBatchWindow]
  batchWindow --> merkleCompute[ComputeMerkleTree]
  merkleCompute --> submitTx[SubmitRootTransaction]
  submitTx --> waitConfirm[WaitForConfirmations]
  waitConfirm --> persistReceipt[PersistReceiptAndBatchStatus]
  persistReceipt --> publishAnchored[PublishAnchorConfirmedEvent]

Batch states:

  • open
  • sealed
  • submitted
  • confirmed
  • failed
  • reconcile_pending

Reconciliation and Replay ​

Reconciliation job:

  • compares submitted batches vs on-chain receipts
  • backfills missed confirmations
  • marks stale submissions for replay

Replay rules:

  • replay allowed only for failed|reconcile_pending batches
  • replay creates new transaction record linked to same batch id and replay attempt index
  • event-level dedupe by leaf_hash

Failure Handling ​

Chain unavailable ​

  • Keep staging leaves in durable store.
  • Continue processing points normally.
  • Alert on batch window overrun.

Delayed confirmations ​

  • Maintain submitted state with confirmation polling.
  • Expose eventual consistency window in operator dashboards.

Transaction revert ​

  • Mark batch as failed.
  • run replay with configurable gas/nonce strategy.

Adapter outage ​

  • Circuit-break external chain adapter.
  • queue retry with exponential backoff.

Security Controls ​

  • Signing key isolation and least privilege.
  • Strict separation between ledger DB credentials and chain signing credentials.
  • Immutable audit log for all anchor submissions and replay attempts.
  • Integrity check on merkle input ordering per batch.

Verification Surfaces ​

Internal verification API:

  • query by ledger_entry_id returns:
    • leaf_hash
    • batch_id
    • merkle_root
    • tx_hash
    • inclusion proof path

Public verification surface (later phase):

  • verify a provided proof package against chain root.

Operational Metrics ​

  • anchor_batch_open_count
  • anchor_batch_confirm_latency_seconds
  • anchor_failure_rate
  • anchor_replay_count
  • orphan_leaf_count
  • proof_query_success_rate

Data Retention ​

  • Keep anchor metadata and proofs for audit lifetime.
  • Keep pseudonym mapping only as long as legal/compliance policy allows.
  • Ensure erasure workflow severs mapping while preserving immutable chain proofs.