# API Reference

## 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`:

```protobuf
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:**

```protobuf
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:**

```protobuf
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):**

```bash
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:**

```protobuf
message SubmitBatchRequest {
  repeated Transaction transactions = 1;
}
```

**Response:**

```protobuf
message SubmitBatchResponse {
  repeated SubmitTransactionResponse responses = 1;
}
```

#### Status and Monitoring

**`GetStatus`**

Get current sequencer status and metrics.

**Request:**

```protobuf
message GetStatusRequest {}
```

**Response:**

```protobuf
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:**

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

**Response Stream:**

```protobuf
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:**

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

**Response:**

```protobuf
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:**

```protobuf
message GetTickRequest {
  uint64 tick_number = 1;
}
```

**Response:**

```protobuf
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:**

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

**Response:**

```protobuf
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:

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

Error responses:

```json
{
  "error": "Error description"
}
```

#### Status Endpoint

**`GET /api/v1/status`**

Get sequencer status and metrics.

**Response:**

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

**Example:**

```bash
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:**

```json
{
  "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:**

```bash
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:**

```json
{
  "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:**

```bash
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:**

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

**Example:**

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

#### Health Check

**`GET /api/v1/health`**

Simple health check endpoint.

**Response:**

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

**Example:**

```bash
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

1. **No Authentication**: Current APIs are unauthenticated
2. **Input Validation**: All inputs are validated for format and size
3. **Rate Limiting**: Basic queue-based limiting prevents resource exhaustion
4. **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)

```bash
# 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)

```bash
# 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)

```bash
# 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:

```rust
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:

```bash
# 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

```json
{
  "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:

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

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