Skip to content

Commit 2e9a2ac

Browse files
manav2401claude
andauthored
feat(evmonly): add eth_subscribe("logs") to the EVM-only RPC (#4669)
Stacked over #4668 This PR adds support to subscribe to logs via WebSocket. `eth_subscribe("logs")`: pushes the logs matching a filter as each block executes. It can also replay past blocks from a given fromBlock. It uses the same cursor rules and caps as `eth_getFilterChanges`, so the two agree on ranges and pruning. A failed poll pushes an `{"error": ...}` message, as the v2 RPC does. Open log subscriptions are capped by the new `[giga.rpc]` key `max_subscriptions_logs` (default 1000, as on the v2 RPC), counted separately from newHeads. Test coverage: WebSocket tests (live, past blocks, toBlock, blockHash, caps) and a new check in the Autobahn Basic suite. --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent f70ea4f commit 2e9a2ac

11 files changed

Lines changed: 532 additions & 45 deletions

File tree

‎giga/config/config.go‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,8 @@ type RPCConfig struct {
8282
// MaxSubscriptionsNewHead caps open eth_subscribe("newHeads") subscriptions across all
8383
// connections.
8484
MaxSubscriptionsNewHead uint64 `mapstructure:"max_subscriptions_new_head"`
85+
// MaxSubscriptionsLogs caps open eth_subscribe("logs") subscriptions across all connections.
86+
MaxSubscriptionsLogs uint64 `mapstructure:"max_subscriptions_logs"`
8587
// MaxSubscriptionsPerConnection caps the open subscriptions of a single WebSocket connection.
8688
MaxSubscriptionsPerConnection uint64 `mapstructure:"max_subscriptions_per_connection"`
8789
// MaxRequestBodyBytes caps the size, in bytes, of one HTTP request body or WebSocket message.
@@ -138,6 +140,7 @@ var DefaultConfig = Config{
138140
// The same limits the v2 EVM RPC defaults to.
139141
RPC: RPCConfig{
140142
MaxSubscriptionsNewHead: 10_000,
143+
MaxSubscriptionsLogs: 1000,
141144
MaxSubscriptionsPerConnection: 100,
142145
MaxRequestBodyBytes: 5 * 1024 * 1024,
143146
MaxConcurrentRequestBytes: 128 * 1024 * 1024,
@@ -190,6 +193,7 @@ const (
190193
FlagExecutionEvmWsPort = "giga.execution.evm_ws_port"
191194
FlagExecutionGCPercent = "giga.execution.gc_percent"
192195
FlagRPCMaxSubscriptionsNewHead = "giga.rpc.max_subscriptions_new_head"
196+
FlagRPCMaxSubscriptionsLogs = "giga.rpc.max_subscriptions_logs"
193197
FlagRPCMaxSubscriptionsPerConnection = "giga.rpc.max_subscriptions_per_connection"
194198
FlagRPCMaxRequestBodyBytes = "giga.rpc.max_request_body_bytes"
195199
FlagRPCMaxConcurrentRequestBytes = "giga.rpc.max_concurrent_request_bytes"
@@ -290,6 +294,11 @@ func ReadConfig(opts AppOptions) (Config, error) {
290294
return cfg, fmt.Errorf("%s: %w", FlagRPCMaxSubscriptionsNewHead, err)
291295
}
292296
}
297+
if v := opts.Get(FlagRPCMaxSubscriptionsLogs); v != nil {
298+
if cfg.RPC.MaxSubscriptionsLogs, err = cast.ToUint64E(v); err != nil {
299+
return cfg, fmt.Errorf("%s: %w", FlagRPCMaxSubscriptionsLogs, err)
300+
}
301+
}
293302
if v := opts.Get(FlagRPCMaxSubscriptionsPerConnection); v != nil {
294303
if cfg.RPC.MaxSubscriptionsPerConnection, err = cast.ToUint64E(v); err != nil {
295304
return cfg, fmt.Errorf("%s: %w", FlagRPCMaxSubscriptionsPerConnection, err)
@@ -519,6 +528,9 @@ gc_percent = {{ .Giga.Execution.GCPercent }}
519528
# connections.
520529
max_subscriptions_new_head = {{ .Giga.RPC.MaxSubscriptionsNewHead }}
521530
531+
# max_subscriptions_logs caps open eth_subscribe("logs") subscriptions across all connections.
532+
max_subscriptions_logs = {{ .Giga.RPC.MaxSubscriptionsLogs }}
533+
522534
# max_subscriptions_per_connection caps the open subscriptions of a single WebSocket connection.
523535
max_subscriptions_per_connection = {{ .Giga.RPC.MaxSubscriptionsPerConnection }}
524536

‎giga/config/config_test.go‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ func TestRPCDefaultsMatchTheV2EVMRPC(t *testing.T) {
4444
v2 := evmrpcconfig.DefaultConfig
4545
r := gigaconfig.DefaultConfig.RPC
4646
require.Equal(t, v2.MaxSubscriptionsNewHead, r.MaxSubscriptionsNewHead)
47+
require.Equal(t, v2.MaxSubscriptionsLogs, r.MaxSubscriptionsLogs)
4748
require.Equal(t, v2.MaxRequestBodyBytes, int64(r.MaxRequestBodyBytes))
4849
require.Equal(t, v2.MaxConcurrentRequestBytes, r.MaxConcurrentRequestBytes)
4950
require.Equal(t, v2.WSAdmissionTimeout, r.WSAdmissionTimeout)
@@ -90,6 +91,7 @@ func TestReadConfigReadsEveryKey(t *testing.T) {
9091
"giga.execution.evm_rpc_port": "8600",
9192
"giga.execution.evm_ws_port": "8601",
9293
"giga.rpc.max_subscriptions_new_head": "20",
94+
"giga.rpc.max_subscriptions_logs": "15",
9395
"giga.rpc.max_subscriptions_per_connection": "5",
9496
"giga.rpc.max_request_body_bytes": "2048",
9597
"giga.rpc.max_concurrent_request_bytes": "4096",
@@ -127,6 +129,7 @@ func TestReadConfigReadsEveryKey(t *testing.T) {
127129
},
128130
RPC: gigaconfig.RPCConfig{
129131
MaxSubscriptionsNewHead: 20,
132+
MaxSubscriptionsLogs: 15,
130133
MaxSubscriptionsPerConnection: 5,
131134
MaxRequestBodyBytes: 2048,
132135
MaxConcurrentRequestBytes: 4096,
@@ -165,6 +168,7 @@ func TestReadConfigRejectsUnusableValues(t *testing.T) {
165168
"evm ws port too high": {"giga.execution.evm_ws_port": "65536"},
166169
"evm ws port is rpc port": {"giga.execution.evm_ws_port": "8545"},
167170
"negative subscription cap": {"giga.rpc.max_subscriptions_new_head": "-1"},
171+
"non-numeric logs cap": {"giga.rpc.max_subscriptions_logs": "lots"},
168172
"non-numeric per-connection cap": {"giga.rpc.max_subscriptions_per_connection": "many"},
169173
"zero request body size": {"giga.rpc.max_request_body_bytes": "0"},
170174
"negative request body size": {"giga.rpc.max_request_body_bytes": "-1"},

‎giga/evmonly/rpc/filter_poll_test.go‎

Lines changed: 15 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import (
55
"errors"
66
"math/big"
77
"net/http/httptest"
8+
"sync/atomic"
89
"testing"
910
"time"
1011

@@ -25,16 +26,17 @@ import (
2526
type pollFixture struct {
2627
api *filterAPI
2728
store *evmonly.MemoryReceiptStore
28-
head uint64
29+
head atomic.Uint64
2930
}
3031

3132
func newPollFixture(t *testing.T) *pollFixture {
3233
t.Helper()
33-
fx := &pollFixture{store: filterFixtureStore(t), head: 9}
34+
fx := &pollFixture{store: filterFixtureStore(t)}
35+
fx.head.Store(9)
3436
backend := filterFixtureBackend(t, 0)
35-
backend.blockNumber = func() uint64 { return fx.head }
37+
backend.blockNumber = fx.head.Load
3638
backend.blockByHash = func(ctx context.Context, req *coretypes.RequestBlockByHash) (*coretypes.ResultBlock, error) {
37-
return filterFixtureBackend(t, fx.head).BlockByHash(ctx, req)
39+
return filterFixtureBackend(t, fx.head.Load()).BlockByHash(ctx, req)
3840
}
3941
fx.api = &filterAPI{
4042
backend: backend,
@@ -48,16 +50,16 @@ func newPollFixture(t *testing.T) *pollFixture {
4850
// commit indexes one contract A log with topic X at the next height and moves the head to it.
4951
func (fx *pollFixture) commit(t *testing.T) uint64 {
5052
t.Helper()
51-
fx.head++
52-
hash := filterTxHash(fx.head, 0)
53+
height := fx.head.Add(1)
54+
hash := filterTxHash(height, 0)
5355
require.NoError(t, fx.store.SetReceipts(sdk.Context{}.WithContext(t.Context()), []receipt.ReceiptRecord{{
5456
TxHash: hash,
55-
Receipt: &evmtypes.Receipt{TxHashHex: hash.Hex(), BlockNumber: fx.head, Logs: []*evmtypes.Log{
57+
Receipt: &evmtypes.Receipt{TxHashHex: hash.Hex(), BlockNumber: height, Logs: []*evmtypes.Log{
5658
{Address: filterContractA.Hex(), Topics: []string{filterTopicX.Hex()}},
5759
}},
5860
}}))
59-
require.NoError(t, fx.store.SetLatestVersion(int64(fx.head))) //nolint:gosec // test heights are small
60-
return fx.head
61+
require.NoError(t, fx.store.SetLatestVersion(int64(height))) //nolint:gosec // test heights are small
62+
return height
6163
}
6264

6365
func logBlocks(logs []*ethtypes.Log) []uint64 {
@@ -263,17 +265,17 @@ func TestGetFilterChangesPollsBlockHashes(t *testing.T) {
263265
}
264266

265267
require.Empty(t, poll())
266-
fx.head += 2
268+
fx.head.Add(2)
267269
require.Equal(t, []common.Hash{filterBlockHash(10), filterBlockHash(11)}, poll())
268270
require.Empty(t, poll())
269-
fx.head++
271+
fx.head.Add(1)
270272
require.Equal(t, []common.Hash{filterBlockHash(12)}, poll())
271273

272274
_, err = fx.api.GetFilterLogs(t.Context(), id)
273275
require.ErrorIs(t, err, errFilterNotFound)
274276

275277
// A filter left behind by more than maxBlockFilterHashes blocks is removed.
276-
fx.head += fx.api.maxBlockFilterHashes + 1
278+
fx.head.Add(fx.api.maxBlockFilterHashes + 1)
277279
_, err = fx.api.GetFilterChanges(t.Context(), id)
278280
require.ErrorIs(t, err, errFilterNotFound)
279281
_, err = fx.api.GetFilterChanges(t.Context(), id)
@@ -293,7 +295,7 @@ func TestGetFilterChangesKeepsBlockHashesAfterAFailedLookup(t *testing.T) {
293295
}
294296
id, err := fx.api.NewBlockFilter(t.Context())
295297
require.NoError(t, err)
296-
fx.head += 2
298+
fx.head.Add(2)
297299

298300
// The lookup of block 11 fails after block 10's succeeded.
299301
_, err = fx.api.GetFilterChanges(t.Context(), id)

‎giga/evmonly/rpc/server.go‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -165,12 +165,13 @@ func newHandler(backend Backend, receiptStore receipt.ReceiptStore, limits gigac
165165
if err := rpcServer.RegisterName("eth", &blockAPI{backend: backend, store: receiptStore}); err != nil {
166166
return nil, fmt.Errorf("register EVM-only block RPC: %w", err)
167167
}
168-
if err := rpcServer.RegisterName("eth", &filterAPI{
168+
logs := &filterAPI{
169169
backend: backend,
170170
store: receiptStore,
171171
filters: newFilterRegistry(limits.FilterTimeout, limits.MaxFilters),
172172
maxBlockFilterHashes: limits.MaxBlockFilterHashes,
173-
}); err != nil {
173+
}
174+
if err := rpcServer.RegisterName("eth", logs); err != nil {
174175
return nil, fmt.Errorf("register EVM-only filter RPC: %w", err)
175176
}
176177
if err := rpcServer.RegisterName("debug", newDebugAPI(backend, receiptStore, limits)); err != nil {
@@ -182,8 +183,8 @@ func newHandler(backend Backend, receiptStore receipt.ReceiptStore, limits gigac
182183
if err := rpcServer.RegisterName("web3", &web3API{}); err != nil {
183184
return nil, fmt.Errorf("register EVM-only web3 RPC: %w", err)
184185
}
185-
subscriptions := newSubscriptionLimiter(limits.MaxSubscriptionsNewHead, limits.MaxSubscriptionsPerConnection)
186-
if err := rpcServer.RegisterName("eth", &subscribeAPI{backend: backend, store: receiptStore, limits: subscriptions}); err != nil {
186+
subscriptions := newSubscriptionLimiter(limits.MaxSubscriptionsNewHead, limits.MaxSubscriptionsLogs, limits.MaxSubscriptionsPerConnection)
187+
if err := rpcServer.RegisterName("eth", &subscribeAPI{backend: backend, store: receiptStore, logs: logs, limits: subscriptions}); err != nil {
187188
return nil, fmt.Errorf("register EVM-only subscription RPC: %w", err)
188189
}
189190
return rpcServer, nil

‎giga/evmonly/rpc/subscribe.go‎

Lines changed: 134 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,10 @@ import (
44
"context"
55
"errors"
66
"fmt"
7+
"time"
78

9+
"github.com/ethereum/go-ethereum/common/hexutil"
10+
"github.com/ethereum/go-ethereum/eth/filters"
811
ethrpc "github.com/ethereum/go-ethereum/rpc"
912

1013
"github.com/sei-protocol/sei-chain/sei-db/ledger_db/receipt"
@@ -13,12 +16,142 @@ import (
1316
"github.com/sei-protocol/sei-chain/sei-tendermint/rpc/coretypes"
1417
)
1518

19+
// logsRetryInterval is how long a logs subscription waits to poll again when an executed block's
20+
// receipts are not indexed yet.
21+
const logsRetryInterval = 100 * time.Millisecond
22+
1623
type subscribeAPI struct {
1724
backend Backend
1825
store receipt.ReceiptStore
26+
logs *filterAPI
1927
limits *subscriptionLimiter
2028
}
2129

30+
// logsErrorNotification is what a logs subscription pushes for a poll that failed. BlockNumber is
31+
// the block whose logs were skipped when the subscription continues past it.
32+
type logsErrorNotification struct {
33+
Error string `json:"error"`
34+
BlockNumber *hexutil.Uint64 `json:"blockNumber,omitempty"`
35+
}
36+
37+
// Logs serves eth_subscribe("logs"), pushing each log crit matches as blocks execute, polled
38+
// through the same cursor as eth_getFilterChanges. A failed poll pushes a logsErrorNotification;
39+
// the stream continues only past a block whose logs alone exceed the log caps.
40+
func (api *subscribeAPI) Logs(ctx context.Context, crit *filters.FilterCriteria) (*ethrpc.Subscription, error) {
41+
notifier, ok := ethrpc.NotifierFromContext(ctx)
42+
if !ok {
43+
return nil, ethrpc.ErrNotificationsUnsupported
44+
}
45+
criteria := subscriptionLogCriteria(crit)
46+
cursor, err := api.logs.pollStart(criteria)
47+
if err != nil {
48+
return nil, err
49+
}
50+
executed, err := api.backend.ExecutedBlocks()
51+
if err != nil {
52+
return nil, err
53+
}
54+
connection := ethrpc.PeerInfoFromContext(ctx).RemoteAddr
55+
if err := api.limits.acquireLogs(connection); err != nil {
56+
return nil, err
57+
}
58+
rpcSub := notifier.CreateSubscription()
59+
go func() {
60+
// The stream ends on eth_unsubscribe, when the connection drops, or once a bounded query
61+
// is delivered, and its slot frees with it.
62+
defer api.limits.releaseLogs(connection)
63+
api.streamLogs(context.WithoutCancel(ctx), notifier, rpcSub, executed, criteria, cursor)
64+
}()
65+
return rpcSub, nil
66+
}
67+
68+
// subscriptionLogCriteria returns the criteria a logs subscription polls with. A fromBlock of 0
69+
// with a tag toBlock, which ethclient sends for an open-ended query, is treated as an omitted
70+
// fromBlock.
71+
func subscriptionLogCriteria(crit *filters.FilterCriteria) filters.FilterCriteria {
72+
if crit == nil {
73+
return filters.FilterCriteria{}
74+
}
75+
if crit.FromBlock != nil && crit.FromBlock.Sign() == 0 && crit.ToBlock != nil && crit.ToBlock.Sign() < 0 {
76+
return filters.FilterCriteria{Addresses: crit.Addresses, Topics: crit.Topics}
77+
}
78+
return *crit
79+
}
80+
81+
func (api *subscribeAPI) streamLogs(
82+
ctx context.Context,
83+
notifier *ethrpc.Notifier,
84+
rpcSub *ethrpc.Subscription,
85+
executed utils.AtomicRecv[atypes.ExecutedBlocks],
86+
crit filters.FilterCriteria,
87+
cursor uint64,
88+
) {
89+
// This goroutine is outside go-ethereum's per-call recovery, so a panic ends the subscription
90+
// rather than the node.
91+
defer func() {
92+
if r := recover(); r != nil {
93+
logger.Error("logs: stream panicked", "subscription", rpcSub.ID, "panic", r)
94+
}
95+
}()
96+
ctx, cancel := subscriptionContext(ctx, rpcSub.Err())
97+
defer cancel()
98+
for {
99+
if _, err := executed.Wait(ctx, func(w atypes.ExecutedBlocks) bool { return uint64(w.Latest().Number) >= cursor }); err != nil {
100+
return
101+
}
102+
logs, next, err := api.logs.pollLogs(ctx, crit, cursor)
103+
if err != nil {
104+
if ctx.Err() != nil || notifier.Notify(rpcSub.ID, newLogsErrorNotification(err)) != nil {
105+
return
106+
}
107+
var oversized *oversizedBlockError
108+
if !errors.As(err, &oversized) {
109+
return
110+
}
111+
}
112+
for _, lg := range logs {
113+
if err := notifier.Notify(rpcSub.ID, lg); err != nil {
114+
return
115+
}
116+
}
117+
if logsExhausted(crit, next) {
118+
return
119+
}
120+
if next == cursor {
121+
select {
122+
case <-ctx.Done():
123+
return
124+
case <-time.After(logsRetryInterval):
125+
}
126+
}
127+
cursor = next
128+
}
129+
}
130+
131+
// subscriptionContext returns a context derived from ctx that is cancelled once subErr closes,
132+
// which happens on eth_unsubscribe and when the connection drops, or once cancel is called.
133+
func subscriptionContext(ctx context.Context, subErr <-chan error) (context.Context, context.CancelFunc) {
134+
ctx, cancel := context.WithCancel(ctx)
135+
go func() {
136+
select {
137+
case <-subErr:
138+
cancel()
139+
case <-ctx.Done():
140+
}
141+
}()
142+
return ctx, cancel
143+
}
144+
145+
func newLogsErrorNotification(err error) logsErrorNotification {
146+
notification := logsErrorNotification{Error: err.Error()}
147+
var oversized *oversizedBlockError
148+
if errors.As(err, &oversized) {
149+
height := hexutil.Uint64(oversized.height)
150+
notification.BlockNumber = &height
151+
}
152+
return notification
153+
}
154+
22155
// NewHeads serves eth_subscribe("newHeads"), pushing one Ethereum header per
23156
// block executed after the subscription is created.
24157
func (api *subscribeAPI) NewHeads(ctx context.Context) (*ethrpc.Subscription, error) {
@@ -64,14 +197,8 @@ func (api *subscribeAPI) streamHeads(
64197
logger.Error("newHeads: stream panicked", "subscription", rpcSub.ID, "panic", r)
65198
}
66199
}()
67-
ctx, cancel := context.WithCancel(ctx)
200+
ctx, cancel := subscriptionContext(ctx, rpcSub.Err())
68201
defer cancel()
69-
go func() {
70-
// Err closes on eth_unsubscribe and when the connection drops; that is
71-
// the only way this stream ends.
72-
<-rpcSub.Err()
73-
cancel()
74-
}()
75202
for next := last + 1; ; next++ {
76203
window, err := executed.Wait(ctx, func(w atypes.ExecutedBlocks) bool { return w.Latest().Number >= next })
77204
if err != nil {

0 commit comments

Comments
 (0)