API Reference

How to interact with Continuum microsecond sequencer [Testnet]

Continuum Sequencer API Reference

This document provides comprehensive reference for both the gRPC and REST APIs of the Continuum Sequencer.

Overview

The Continuum Sequencer provides dual API access:

gRPC API: High-performance binary protocol for production integrations
REST API: JSON-based API for web applications and debugging

Both APIs provide access to transaction submission, tick querying, and chain state inspection.

Base URLs

gRPC: Default 0.0.0.0:9090
REST: Default 0.0.0.0:8080 with base path /api/v1

Authentication

Currently, the APIs are unauthenticated. Authentication and authorization will be added in future phases.

gRPC API

Service Definition

The gRPC service is defined in sequencer.proto:

service SequencerService {
  rpc SubmitTransaction(SubmitTransactionRequest) returns (SubmitTransactionResponse);
  rpc SubmitBatch(SubmitBatchRequest) returns (SubmitBatchResponse);
  rpc GetStatus(GetStatusRequest) returns (GetStatusResponse);
  rpc StreamTicks(StreamTicksRequest) returns (stream Tick);
  rpc GetTransaction(GetTransactionRequest) returns (GetTransactionResponse);
  rpc GetTick(GetTickRequest) returns (GetTickResponse);
  rpc GetChainState(GetChainStateRequest) returns (GetChainStateResponse);
}

Transaction Submission

SubmitTransaction

Submit a single transaction for ordering.

Request:

message SubmitTransactionRequest {
  Transaction transaction = 1;
}

message Transaction {
  string tx_id = 1;                    // Unique transaction identifier
  bytes payload = 2;                   // Application-specific data
  bytes signature = 3;                 // Client signature
  bytes public_key = 4;                // Client public key
  uint64 nonce = 5;                    // Replay protection nonce
  uint64 timestamp = 6;                // Client timestamp (microseconds)
}

Response:

message SubmitTransactionResponse {
  uint64 sequence_number = 1;          // Assigned sequence number
  uint64 expected_tick = 2;            // Expected inclusion tick
  string tx_hash = 3;                  // Transaction hash (8-char hex)
}

Example (grpcurl):

grpcurl -plaintext -d '{
  "transaction": {
    "tx_id": "tx_001",
    "payload": "SGVsbG8gV29ybGQ=",
    "signature": "c2lnbmF0dXJl",
    "public_key": "cHVibGljX2tleQ==",
    "nonce": 1,
    "timestamp": 1672531200000000
  }
}' localhost:9090 continuum.sequencer.v1.SequencerService/SubmitTransaction

SubmitBatch

Submit multiple transactions in a single request.

Request:

message SubmitBatchRequest {
  repeated Transaction transactions = 1;
}

Response:

message SubmitBatchResponse {
  repeated SubmitTransactionResponse responses = 1;
}

Status and Monitoring

GetStatus

Get current sequencer status and metrics.

Request:

message GetStatusRequest {}

Response:

message GetStatusResponse {
  uint64 current_tick = 1;             // Current tick number
  uint64 total_transactions = 2;       // Total transactions processed
  uint64 pending_transactions = 3;     // Transactions in queue
  uint64 uptime_seconds = 4;           // Sequencer uptime
  double transactions_per_second = 5;  // Current TPS rate
}

StreamTicks

Stream live ticks as they are produced.

Request:

message StreamTicksRequest {
  uint64 start_tick = 1;               // Start from this tick (0 = latest)
}

Response Stream:

message Tick {
  uint64 tick_number = 1;
  VdfProof vdf_proof = 2;
  repeated OrderedTransaction transactions = 3;
  string transaction_batch_hash = 4;
  uint64 timestamp = 5;
  string previous_output = 6;           // Previous VDF output (hex)
}

Data Queries

GetTransaction

Lookup a transaction by its hash.

Request:

message GetTransactionRequest {
  string tx_hash = 1;                  // 8-character hex hash
}

Response:

message GetTransactionResponse {
  OrderedTransaction transaction = 1;   // Transaction details
  uint64 tick_number = 2;              // Inclusion tick
  bool found = 3;                      // Whether transaction exists
}

GetTick

Retrieve a specific tick by number. The sequencer maintains 1 million ticks in memory for fast access. Older ticks are automatically archived to disk and can still be retrieved, though with slightly higher latency.

Request:

message GetTickRequest {
  uint64 tick_number = 1;
}

Response:

message GetTickResponse {
  Tick tick = 1;                       // Tick details
  bool found = 2;                      // Whether tick exists
}

Archive Behavior:

Recent ticks (up to 1M) are served from memory
Older ticks are automatically archived to disk at data/archive/
Archived ticks are organized in subdirectories (10k ticks per directory)
Both memory and archived ticks are transparently accessible via the same API

GetChainState

Get chain state summary with recent ticks.

Request:

message GetChainStateRequest {
  uint32 tick_limit = 1;               // Max recent ticks to return
}

Response:

message GetChainStateResponse {
  uint64 chain_height = 1;             // Latest tick number
  uint64 total_transactions = 2;       // Total processed transactions
  repeated Tick recent_ticks = 3;      // Recent ticks
  map<string, uint64> tx_to_tick_sample = 4;  // Sample mappings
}

REST API

All REST endpoints return JSON responses with appropriate HTTP status codes.

Base Response Format

Success responses follow this structure:

{
  "found": true,
  "data": { ... }
}

Error responses:

{
  "error": "Error description"
}

Status Endpoint

GET /api/v1/status

Get sequencer status and metrics.

Response:

{
  "chain_height": 1234,
  "total_transactions": 5678,
  "latest_tick": 1234,
  "status": "running"
}

Example:

curl http://localhost:8080/api/v1/status

Transaction Submission

Note: Transaction submission via REST API is not yet implemented. Currently, transactions must be submitted through the gRPC API. REST submission will be added in a future release.

To submit transactions, use the gRPC SubmitTransaction or SubmitBatch endpoints as documented in the gRPC API section above.

Transaction Queries

GET /api/v1/tx/{hash}

Lookup transaction by 8-character hex hash.

Parameters:

hash: 8-character hexadecimal transaction hash

Response:

{
  "tx_hash": "deadbeef",
  "tick_number": 123,
  "sequence_number": 456,
  "found": true,
  "transaction": {
    "tx_id": "tx_001",
    "nonce": 1,
    "ingestion_timestamp": 1672531200000000,
    "payload_size": 256
  }
}

Example:

curl http://localhost:8080/api/v1/tx/deadbeef

How Transaction Hashes Work:

Transaction hashes are 8-character hexadecimal strings (32 bits)
They represent the first 4 bytes of the SHA256 hash of the transaction data
The hash is computed from the serialized transaction including: tx_id, payload, signature, public_key, nonce, and timestamp
Due to the shortened hash, collisions are possible but rare in practice

Tick Queries

GET /api/v1/tick/{number}

Retrieve tick by number. Transparently serves from memory (recent 1M ticks) or disk archive (older ticks).

Parameters:

number: Tick number (integer)

Response:

{
  "tick_number": 123,
  "found": true,
  "tick": {
    "tick_number": 123,
    "timestamp": 1672531200000000,
    "transaction_count": 50,
    "transaction_batch_hash": "abcd1234...",
    "vdf_iterations": 27,
    "previous_output": "efgh5678..."
  }
}

Example:

curl http://localhost:8080/api/v1/tick/123

Archive Notes:

Memory buffer: 1,000,000 most recent ticks
Older ticks archived to: data/archive/{subdir}/tick_{number}.json
Archive lookup adds ~10-50ms latency vs memory access

GET /api/v1/ticks/recent

Get recent ticks with pagination.

Query Parameters:

limit (optional): Maximum ticks to return (default: 20, max: 100)
offset (optional): Offset for pagination (default: 0)

Response:

{
  "ticks": [
    {
      "tick_number": 125,
      "timestamp": 1672531200000000,
      "transaction_count": 42
    },
    {
      "tick_number": 124,
      "timestamp": 1672531199900000,
      "transaction_count": 38
    }
  ],
  "total": 2
}

Example:

curl "http://localhost:8080/api/v1/ticks/recent?limit=10"

Health Check

GET /api/v1/health

Simple health check endpoint.

Response:

{
  "status": "healthy",
  "timestamp": 1672531200
}

Example:

curl http://localhost:8080/api/v1/health

Error Handling

HTTP Status Codes

200 OK: Request successful
400 Bad Request: Invalid request format or parameters
404 Not Found: Resource not found (transaction, tick)
500 Internal Server Error: Server error
503 Service Unavailable: Service temporarily unavailable

gRPC Status Codes

OK: Request successful
INVALID_ARGUMENT: Invalid request parameters
NOT_FOUND: Resource not found
RESOURCE_EXHAUSTED: Queue full or rate limited
INTERNAL: Internal server error

Rate Limiting

Current implementation includes basic backpressure:

Transaction queue has configurable limits
Batch submissions continue processing even if individual transactions fail
gRPC streaming has channel-based backpressure

Data Types

Transaction Hash Format

Transaction hashes are 8-character hexadecimal strings representing the first 32 bits of the SHA256 hash of transaction data.

Example: deadbeef

Timestamps

All timestamps are in microseconds since Unix epoch (UTC).

Example: 1672531200000000 = 2023-01-01 00:00:00 UTC

VDF Proofs

VDF proofs contain:

input: Hex-encoded input bytes
output: Hex-encoded output bytes
proof: Hex-encoded proof bytes
iterations: Number of iterations performed

Tick Numbering

Ticks are numbered sequentially starting from 1. Tick 0 is reserved for genesis.

Security Considerations

No Authentication: Current APIs are unauthenticated
Input Validation: All inputs are validated for format and size
Rate Limiting: Basic queue-based limiting prevents resource exhaustion
Cryptographic Integrity: VDF proofs ensure tick authenticity

Performance Characteristics

Target Tick Time: ≤100 microseconds
Transaction Throughput: 100k+ tx/s ingestion capacity
VDF Verification: Batch verification provides 10x+ speedup
Memory Usage: Configurable tick retention (default: 1,000,000 ticks)

Complete Transaction Flow Example

Here's a complete example of submitting a transaction via gRPC and then querying it via REST:

1. Submit Transaction (gRPC)

# Submit a transaction using grpcurl
grpcurl -plaintext -d '{
  "transaction": {
    "tx_id": "my_unique_tx_001",
    "payload": "SGVsbG8gQ29udGludXVtIQ==",
    "signature": "c2lnbmF0dXJlX2RhdGE=",
    "public_key": "cHVibGljX2tleV9kYXRh",
    "nonce": 12345,
    "timestamp": 1672531200000000
  }
}' localhost:9090 continuum.sequencer.v1.SequencerService/SubmitTransaction

# Response:
{
  "sequence_number": "789",
  "expected_tick": "150",
  "tx_hash": "a1b2c3d4"
}

2. Query Transaction Status (REST)

# Use the tx_hash from the response to query the transaction
curl http://localhost:8080/api/v1/tx/a1b2c3d4

# Response:
{
  "tx_hash": "a1b2c3d4",
  "tick_number": 150,
  "sequence_number": 789,
  "found": true,
  "transaction": {
    "tx_id": "6d795f756e697175655f74785f303031",
    "nonce": 12345,
    "ingestion_timestamp": 1672531200000000,
    "payload_size": 17
  }
}

3. Verify Inclusion in Tick (REST)

# Query the tick that contains the transaction
curl http://localhost:8080/api/v1/tick/150

# Response shows the tick with your transaction included
{
  "tick_number": 150,
  "found": true,
  "tick": {
    "tick_number": 150,
    "timestamp": 1672531200100000,
    "transaction_count": 42,
    "transaction_batch_hash": "f5e6d7c8b9a0...",
    "vdf_iterations": 27,
    "previous_output": "a1b2c3d4e5f6..."
  }
}

Client Libraries

Rust

The sequencer crate can be used directly as a library:

use sequencer::{SequencerConfig, Sequencer};

let config = SequencerConfig::default();
let sequencer = Sequencer::new(config)?;

gRPC Clients

Generate clients from the protobuf definition for any language:

Go: protoc-gen-go-grpc
Python: grpcio-tools
JavaScript: grpc-web
Java: protoc-gen-grpc-java

REST Clients

Standard HTTP clients work with the REST API:

# curl
curl -X GET http://localhost:8080/api/v1/status

# wget
wget -qO- http://localhost:8080/api/v1/health

# HTTPie
http GET localhost:8080/api/v1/tick/123

Data Storage and Archiving

In-Memory Storage

The sequencer maintains a configurable number of recent ticks in memory for fast access:

Default: 1,000,000 ticks
Configurable: Via max_ticks parameter in ChainState::new()
Access time: Sub-millisecond

Disk Archiving

Older ticks are automatically archived to disk when pruned from memory:

Archive location: data/archive/
Directory structure: {tick_number / 10000}/tick_{10-digit-number}.json
Format: JSON for easy inspection and debugging
Automatic: Archiving happens transparently during pruning
Access: All APIs (GetTick, GetTransaction) automatically check archives

Archive File Example

{
  "tick_number": 123456,
  "vdf_proof": {
    "input": "0x...",
    "output": "0x...",
    "proof": "0x...",
    "iterations": 27
  },
  "transactions": [
    {
      "tx_id": "tx_001",
      "tx_hash": [/* 32 bytes */],
      "sequence_number": 789,
      "payload": [/* bytes */],
      "signature": [/* bytes */],
      "public_key": [/* bytes */],
      "nonce": 12345,
      "ingestion_timestamp": 1672531200000000
    }
  ],
  "batch_hash": [/* 32 bytes */],
  "timestamp": 1672531200000000,
  "previous_vdf_output": [/* bytes */]
}

Monitoring and Observability

Metrics Endpoints

Currently available through:

gRPC GetStatus call
REST /api/v1/status endpoint

Future releases will include:

Prometheus metrics exposition
OpenTelemetry tracing
Structured logging

Log Levels

Configure with RUST_LOG environment variable:

RUST_LOG=sequencer=info,vdf=debug ./target/release/sequencer

Available levels: trace, debug, info, warn, error

PreviousSummary NextArchitecture

Last updated 4 months ago

Good evening

Continuum Sequencer API Reference

Overview

Base URLs

Authentication

gRPC API

Service Definition

Transaction Submission

Status and Monitoring

Data Queries

REST API

Base Response Format

Status Endpoint

Transaction Submission

Transaction Queries

Tick Queries

Health Check

Error Handling

HTTP Status Codes

gRPC Status Codes

Rate Limiting

Data Types

Transaction Hash Format

Timestamps

VDF Proofs

Tick Numbering

Security Considerations

Performance Characteristics

Complete Transaction Flow Example

1. Submit Transaction (gRPC)

2. Query Transaction Status (REST)

3. Verify Inclusion in Tick (REST)

Client Libraries

Rust

gRPC Clients

REST Clients

Data Storage and Archiving

In-Memory Storage

Disk Archiving

Archive File Example

Monitoring and Observability

Metrics Endpoints

Log Levels