System Architecture

Allegro is a preconfirmation payment system for the Tempo blockchain. Users complete chained payments before block finalization using validator-signed certificates that aggregate into Quorum Certificates.

Overview

The system consists of four main component layers. User clients construct and submit transactions to validator sidecars. Sidecars validate transactions and issue certificates. The aggregator backend collects certificates from multiple sidecars and assembles Quorum Certificates. The web frontend provides a browser interface for payments.

flowchart TB
    subgraph Clients["User Clients"]
        Alice
        Bob
        Carol
    end

    subgraph Validators["Validator Sidecars"]
        Dave["Dave Sidecar"]
        Edgar["Edgar Sidecar"]
    end

    subgraph Aggregator["Backend"]
        Backend["fastpay-backend"]
        REST["REST API"]
    end

    subgraph Frontend["Web"]
        Web["React App"]
    end

    Clients --> Validators
    Dave <--> Edgar
    Backend --> Validators
    REST --> Backend
    Web --> REST

This diagram shows the primary data flows between components. User clients submit transactions directly to validator sidecars. Sidecars gossip certificates among themselves. The backend fans out requests to all sidecars and aggregates responses. The web frontend communicates with the backend through REST endpoints.

Payment Flow

A payment progresses through several stages from submission to finality. The sender constructs a FastPayTx containing the payment details, nonce, and expiry. Validator sidecars validate the transaction and return signed certificates. Once enough certificates are collected, they form a Quorum Certificate.

The QC threshold determines how many validator certificates are required. In the demo with two validators, the threshold is 2 of 2. In production deployments, the threshold follows Byzantine fault tolerance requirements at 2f+1 where f is the maximum number of faulty validators tolerated.

sequenceDiagram
    participant Sender
    participant Sidecar1
    participant Sidecar2
    participant Recipient

    Sender->>Sidecar1: SubmitFastPay(tx)
    Sender->>Sidecar2: SubmitFastPay(tx)
    Sidecar1-->>Sender: ValidatorCertificate
    Sidecar2-->>Sender: ValidatorCertificate
    Sender->>Sender: Assemble QC
    Recipient->>Sidecar1: GetBulletinBoard
    Sidecar1-->>Recipient: Certificates
    Recipient->>Recipient: Verify QC

This sequence shows the happy path for a single payment. The sender submits to multiple sidecars in parallel. Each sidecar validates and returns a certificate. The sender assembles the Quorum Certificate locally. The recipient can discover the payment through the bulletin board.

Chained Payments

Recipients can spend received funds before block settlement using parent QC references. Bob receives a payment from Alice and obtains the QC. Bob includes the QC hash as parent_qc_hash in a new payment to Carol. Sidecars validate the parent QC and credit Bob with the incoming amount.

This enables instant chained payments without waiting for on-chain confirmation. The contention key (sender, nonce_key, nonce_seq) prevents double-spending at the Allegro layer.

Crate Structure

The crates form a layered dependency structure. fastpay-types sits at the bottom with no internal dependencies. fastpay-crypto implements the traits from fastpay-types. fastpay-proto generates wire types from protobuf definitions. Higher-level crates depend on these foundations.

Related Documentation

See Validator Sidecar for the gRPC service implementation.

See Aggregator Backend for the REST API and certificate aggregation.

See User Client for the Rust client library.

See Tempo Integration for blockchain-specific details.

See Demo Scenario for the end-to-end demonstration.