⛓️ Protocol: Lifecycle & States

Overview

KAT Bridge uses two distinct authorization paths:

  • Deposits (Kaspa L1 → Kasplex L2): Each of the five independent relayers validates the L1 deposit and attests on L2. The bridge auto-mints once all 5/5 attestations are recorded.

  • Withdrawals (Kasplex L2 → Kaspa L1): Relayers validate the L2 burn and participate in a FROST threshold signing round. The resulting group signature authorizes the L1 release.

Confirmations & Timing

  • Finality requirement: 20 blocks on both chains before acting.

  • Timeout & retries (ops policy): The relayer layer retries an operation once after a failure. If it fails again, admins are notified for manual review/processing.

Lifecycle States

  • Observed: Event detected by custom listeners after 20 confirmations.

  • Pending: Relayers validate and prepare the canonical message for that event.

  • Executed: Destination-chain action performed (L2 mint or L1 release).

  • Finalized: On-chain confirmation recorded and the event is closed.

Deposits (L1 → L2): Attest → Auto-Mint

  1. Observation & Validation: Each relayer independently observes the L1 deposit (20 blocks), validates it, and derives the same event identity.

  2. Attestation: Each relayer attests on L2 from its unique attestor address.

  3. Auto-Mint: After all 5 attestations are recorded for the same event, the bridge mints to the recipient on L2.

Attestor set: The five attestor addresses on L2 are governed/upgradable by on-chain governance.

Liveness: Missing a relayer stalls minting by design (safety > liveness). Operators handle availability via standard SLOs and the retry + admin-notify policy above.

State diagram (L1 → L2)

stateDiagram-v2
    [*] --> Observed
    Observed --> Pending: 20-block L1 confirmation
    Pending --> Attesting
    Attesting --> Executed: All 5 attestations recorded (auto-mint)
    Executed --> Finalized: L2 confirmation
    Finalized --> [*]

Withdrawals (L2 → L1): Burn → FROST Release

  1. Observation & Validation: Relayers detect the L2 burn/withdrawal after 20 blocks and agree on the canonical message.

  2. FROST Round: Each relayer produces a partial signature; the coordinator verifies and assembles the group signature.

  3. Release on L1: The signed L1 release is broadcast and confirmed; the event is finalized.

Coordinator: Runs separately from the five relayers and cannot sign—it only assembles valid shares.

State diagram (L2 → L1)

stateDiagram-v2
    [*] --> Observed
    Observed --> Pending: 20-block L2 confirmation
    Pending --> Signing: FROST round
    Signing --> Executed: Release submitted on L1
    Executed --> Finalized: L1 confirmation
    Finalized --> [*]

Governance Controls

  • Attestor addresses (L2): Upgradable via governance (on-chain voting).

  • Operational policy: Retries and admin notifications are handled off-chain; no protocol change needed.

Guarantees (at a glance)

  • Deposits: Integrity requires 5/5 independent attestations; payload mismatch cannot mint.

  • Withdrawals: Integrity requires a valid FROST group signature; sub-threshold actors cannot release.

  • Finality: No action before 20-block confirmation on the origin chain.

  • Transparency: Governance changes and operator policies are publicly documented in this GitBook.

Previous🔐 Security Model (FROST & Invariants)Next🛠️ On-Chain Contracts & Message Formats