sequencer_client 0.5.0

A library for reading the Arbitrum Sequencer feed.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

# SequencerClient

A Rust library for reading and parsing messages from the Arbitrum sequencer feed into typed transactions.

## Features

### Supported Transaction Types

**Standard L2 Transactions:**
- Legacy transactions
- EIP-2930 transactions (access lists)
- EIP-1559 transactions (dynamic fees)
- EIP-7702 transactions (set code)

**Arbitrum-Specific Transactions:**
- ETH deposits (TxDeposit)
- Retryable tickets (SubmitRetryableTx)
- Batch posting reports (internal transaction type)

### Key Capabilities

- Multiple parallel WebSocket connections for improved throughput
- Automatic reconnection on connection failures
- Out-of-order message buffering and reordering
- Recursive parsing of nested batch transactions
- Stream-based API using Rust async streams

## Motivation

Listening to the sequencer feed is faster than subscribing to RPC logs. Most existing libraries skip batch transactions, which make up approximately 80% of all transactions on Arbitrum. This library handles all transaction types including batched transactions.

## Usage

### Installation

Add to your `Cargo.toml`:

```toml
[dependencies]
sequencer_client = "0.4"
```

### Basic Example

```rust
use futures_util::stream::StreamExt;
use sequencer_client::reader::SequencerReader;
use arb_sequencer_consensus::transactions::ArbTxEnvelope;

#[tokio::main]
async fn main() {
    // Install a default crypto provider (required)
    rustls::crypto::aws_lc_rs::default_provider()
        .install_default()
        .expect("Failed to install rustls crypto provider");

    // Connect to the Arbitrum One sequencer feed
    let url = "wss://arb1-feed.arbitrum.io/feed";
    let chain_id = 42161; // Arbitrum One
    let connections = 10; // Number of parallel WebSocket connections

    let reader = SequencerReader::new(url, chain_id, connections).await;
    let mut stream = reader.into_stream();

    // Process messages from the stream
    while let Some(msg_result) = stream.next().await {
        match msg_result {
            Ok(msg) => {
                println!("Sequence: {}, Transactions: {}",
                    msg.sequence_number,
                    msg.txs.len()
                );

                // Access individual transactions
                for tx in msg.txs {
                    match tx {
                        ArbTxEnvelope::Legacy(tx) => {
                            println!("Legacy tx: {}", tx.tx_hash());
                        }
                        ArbTxEnvelope::Eip1559(tx) => {
                            println!("EIP-1559 tx: {}", tx.tx_hash());
                        }
                        ArbTxEnvelope::DepositTx(tx) => {
                            println!("Deposit from: {}", tx.from());
                        }
                        ArbTxEnvelope::SubmitRetryableTx(tx) => {
                            println!("Retryable ticket from: {}", tx.from());
                        }
                        _ => {}
                    }
                }
            }
            Err(e) => {
                eprintln!("Error: {}", e);
            }
        }
    }
}
```

### SequencerMessage Structure

Each message from the stream contains:

- `sequence_number`: The sequential message number from the feed
- `txs`: Vector of parsed transactions (`Vec<ArbTxEnvelope>`)
- `is_last_in_block`: Whether this is the last message in a block
- `timestamp`: Message timestamp from the L1 header
- `received_at`: Local instant when the message was received
- `l1_header`: L1 header information

### API Notes

**Required Setup:**
- You must install a default crypto provider before creating a `SequencerReader`
- Recommended: `rustls::crypto::aws_lc_rs::default_provider().install_default()`

**Connection Parameters:**
- `url`: WebSocket endpoint (e.g., `wss://arb1-feed.arbitrum.io/feed`)
- `chain_id`: Network chain ID (42161 for Arbitrum One, 42170 for Arbitrum Nova)
- `connections`: Number of parallel WebSocket connections (recommended: less than 10)

**Stream Behavior:**
- Messages are automatically reordered if received out of sequence
- Connections automatically reconnect on failure
- Duplicate messages are filtered out
- The stream yields `Result<SequencerMessage>` items

## About the Type System

This library uses two internal crates for Arbitrum-specific types:

**`arb_sequencer_consensus`**: Contains consensus-layer types for Arbitrum transactions, including deposit transactions, retryable tickets, and batch posting reports. These types extend the standard Alloy transaction types to support Arbitrum's unique transaction formats.

**`arb_sequencer_network`**: Contains network-layer types for the sequencer feed protocol, including message parsing and WebSocket communication structures.