Skip to content

Commit 3562562

Browse files
authored
Cache payer collateral with bounded canonical recovery (#42)
Depends on #41. Merge after that PR. Known payers use immutable cached collateral at the shared observation. A bounded hash-linked history proof keeps unchanged payers warm across canonical polling gaps; incomplete history resets entries for pinned rereads. Funding, withdrawal, reserve, round and Controller target changes invalidate the affected entries, including upgrades with unchanged public proxy addresses. Cold reads share work by payer/recipient and have a global four-key limit with no distinct-key queue. Cancellation, eviction, failures and shutdown preserve those bounds. A durable settlement watermark is recorded with liability release and checked inside admission, preventing pre-settlement collateral from being paired with released liability. Retains recipient-specific reserve/withdrawal semantics, replay guards, durable acknowledgement and redemption protections. Shared implementation and tests retain source attribution. Validation: affected and full repository race suites, vet, canonicality/financial/recovery regressions and diff checks passed on the final reviewed series. Closes #33.
2 parents 9cf4d8f + 77a9b45 commit 3562562

19 files changed

Lines changed: 1317 additions & 115 deletions

‎eth/payment.go‎

Lines changed: 34 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -60,37 +60,39 @@ func (c PaymentChain) activeAt(ctx context.Context, address, recipient ethcommon
6060
return bonding.IsActiveTranscoder(&bind.CallOpts{Context: ctx}, recipient)
6161
}
6262

63-
// Receipt reports a submitted redemption without retrying or resubmitting it.
64-
func (c PaymentChain) Receipt(ctx context.Context, hash ethcommon.Hash) (confirmed, reverted bool, err error) {
63+
// FinalizedReceipt retains canonical inclusion evidence for durable collateral admission.
64+
func (c PaymentChain) FinalizedReceipt(ctx context.Context, hash ethcommon.Hash) (*types.Receipt, error) {
6565
receipt, err := c.Contracts.RPC.TransactionReceipt(ctx, hash)
6666
if errors.Is(err, ethereum.NotFound) {
67-
return false, false, nil
67+
return nil, nil
6868
}
6969
if err != nil {
70-
return false, false, err
70+
return nil, err
7171
}
7272
finalized, err := c.Contracts.RPC.header(ctx, "finalized")
7373
if err != nil {
74-
return false, false, err
74+
return nil, err
7575
}
7676
if finalized.Number == nil {
77-
return false, false, errors.New("invalid finalized header")
77+
return nil, errors.New("invalid finalized header")
7878
}
7979
if (*big.Int)(finalized.Number).Cmp(receipt.BlockNumber) < 0 {
80-
return false, false, nil
80+
return nil, nil
8181
}
8282
canonical, err := c.Contracts.RPC.header(ctx, hexutil.EncodeBig(receipt.BlockNumber))
8383
if err != nil {
84-
return false, false, err
84+
return nil, err
8585
}
8686
if canonical.Hash != receipt.BlockHash {
87-
return false, false, nil
87+
return nil, nil
8888
}
89-
return receipt.Status == types.ReceiptStatusSuccessful, receipt.Status == types.ReceiptStatusFailed, nil
89+
return receipt, nil
9090
}
9191

9292
type ChainSnapshot struct {
9393
Block *big.Int // Protocol L1 block, including on Arbitrum.
94+
Number *big.Int // Execution-chain height, distinct from the L1 clock.
95+
BlockHash ethcommon.Hash
9496
Round *big.Int // Last initialized round.
9597
RoundHash ethcommon.Hash
9698
CurrentRound *big.Int // Protocol round; may exceed the initialized Round.
@@ -158,7 +160,7 @@ func (c PaymentChain) snapshotAt(ctx context.Context, header *miniHeader, curren
158160
if hash == ([32]byte{}) {
159161
return ChainSnapshot{}, errors.New("invalid round block hash")
160162
}
161-
snapshot := ChainSnapshot{Block: block, Round: round, RoundHash: ethcommon.Hash(hash), blockReference: ref, addresses: addresses}
163+
snapshot := ChainSnapshot{Block: block, Number: new(big.Int).Set((*big.Int)(header.Number)), BlockHash: header.Hash, Round: round, RoundHash: ethcommon.Hash(hash), blockReference: ref, addresses: addresses}
162164
if currentRound {
163165
snapshot.CurrentRound, err = rounds.CurrentRound(opts)
164166
if err != nil {
@@ -183,10 +185,20 @@ type SenderInfo struct {
183185
}
184186

185187
func (c PaymentChain) SenderInfo(ctx context.Context, sender, recipient ethcommon.Address) (SenderInfo, error) {
188+
if c.Observer != nil {
189+
if c.Contracts != c.Observer.chain.Contracts {
190+
return SenderInfo{}, errors.New("payment observer belongs to another contract client")
191+
}
192+
return c.Observer.senderInfo(ctx, sender, recipient)
193+
}
186194
snapshot, err := c.Snapshot(ctx)
187195
if err != nil {
188196
return SenderInfo{}, err
189197
}
198+
return c.senderInfoAt(ctx, sender, recipient, snapshot)
199+
}
200+
201+
func (c PaymentChain) senderInfoAt(ctx context.Context, sender, recipient ethcommon.Address, snapshot ChainSnapshot) (SenderInfo, error) {
190202
address, err := c.Contracts.paymentAddress(ctx, snapshot, "ticketBroker")
191203
if err != nil {
192204
return SenderInfo{}, err
@@ -276,29 +288,32 @@ func (c PaymentChain) SubmitRedemption(ctx context.Context, nonces *NonceManager
276288
return nil
277289
}
278290

279-
// IsUsedTicket is ported from go-livepeer/eth/client_ticketbroker.go. The block
280-
// argument also supports the finalized observation needed for node settlement.
281-
func (c PaymentChain) IsUsedTicket(ctx context.Context, hash ethcommon.Hash, block string) (bool, error) {
291+
// TicketUse adapts go-livepeer/eth/client_ticketbroker.go's IsUsedTicket.
292+
// It returns the pinned finalized identity alongside ticket-use evidence.
293+
func (c PaymentChain) TicketUse(ctx context.Context, hash ethcommon.Hash, block string) (bool, ChainSnapshot, error) {
282294
var ref any = block
295+
var observation ChainSnapshot
283296
if block == "finalized" {
284297
header, err := c.Contracts.RPC.header(ctx, "finalized")
285298
if err != nil {
286-
return false, err
299+
return false, ChainSnapshot{}, err
287300
}
288301
if header.Hash == (ethcommon.Hash{}) || header.Number == nil {
289-
return false, errors.New("invalid finalized header")
302+
return false, ChainSnapshot{}, errors.New("invalid finalized header")
290303
}
291304
ref = map[string]any{"blockHash": header.Hash, "requireCanonical": true}
305+
observation = ChainSnapshot{Number: new(big.Int).Set((*big.Int)(header.Number)), BlockHash: header.Hash}
292306
}
293307
address, err := c.Contracts.ResolveAt(ctx, ref, "ticketBroker")
294308
if err != nil {
295-
return false, err
309+
return false, ChainSnapshot{}, err
296310
}
297311
broker, err := contracts.NewTicketBrokerCaller(address, c.Contracts.callerAt(ref))
298312
if err != nil {
299-
return false, err
313+
return false, ChainSnapshot{}, err
300314
}
301-
return broker.UsedTickets(&bind.CallOpts{Context: ctx}, hash)
315+
used, err := broker.UsedTickets(&bind.CallOpts{Context: ctx}, hash)
316+
return used, observation, err
302317
}
303318

304319
// FinalizedNonce pins account state to the same canonical finalized reference

‎eth/payment_contracts_test.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -132,7 +132,7 @@ func TestObserverRegistryScopeAndFinalizedReads(t *testing.T) {
132132
})
133133
chain := o.chain
134134
chain.Observer = o // Its retained registry is deliberately still the old one.
135-
used, err := chain.IsUsedTicket(t.Context(), common.HexToHash("0x9999"), "finalized")
135+
used, _, err := chain.TicketUse(t.Context(), common.HexToHash("0x9999"), "finalized")
136136
require.NoError(t, err)
137137
require.False(t, used, "finalized settlement resolves its own canonical registry")
138138
require.Equal(t, 1, f.Stats().Calls["Controller.getContract"])

‎eth/payment_observer.go‎

Lines changed: 56 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,10 @@ type PaymentObserver struct {
3535
l1Progress time.Time
3636
l1HighWater *big.Int
3737
recipient common.Address
38+
lifecycle context.Context
39+
payers map[payerKey]*payerEntry
40+
payerReads sync.WaitGroup
41+
activeReads int
3842
}
3943

4044
func NewPaymentObserver(chain PaymentChain, requireL1 bool, recipient common.Address) *PaymentObserver {
@@ -44,7 +48,17 @@ func NewPaymentObserver(chain PaymentChain, requireL1 bool, recipient common.Add
4448

4549
// Run has one service-owned caller. Every RPC inherits the service lifetime.
4650
func (o *PaymentObserver) Run(ctx context.Context) {
47-
defer func() { o.mu.Lock(); o.stopped = true; o.mu.Unlock() }()
51+
o.mu.Lock()
52+
lifecycle, cancelReads := context.WithCancel(ctx)
53+
o.lifecycle = lifecycle
54+
o.mu.Unlock()
55+
defer func() {
56+
cancelReads()
57+
o.mu.Lock()
58+
o.stopped = true
59+
o.mu.Unlock()
60+
o.payerReads.Wait()
61+
}()
4862
ticker := time.NewTicker(o.interval)
4963
defer ticker.Stop()
5064
for {
@@ -64,13 +78,20 @@ func (o *PaymentObserver) Run(ctx context.Context) {
6478
type ObserverStatus struct {
6579
ObservedAt, ContactAt, HeadProgressAt, L1ProgressAt time.Time
6680
Healthy, RecipientActive bool
81+
PayerEntries, PayerReads, PayerFailures int
6782
}
6883

6984
func (o *PaymentObserver) Status() ObserverStatus {
7085
o.mu.RLock()
7186
defer o.mu.RUnlock()
7287
healthy := o.validate(o.current) == nil
73-
return ObserverStatus{o.current.observedAt, o.contact, o.progress, o.l1Progress, healthy, healthy && o.recipient != (common.Address{}) && o.current.recipientErr == nil && o.current.recipientActive}
88+
status := ObserverStatus{ObservedAt: o.current.observedAt, ContactAt: o.contact, HeadProgressAt: o.progress, L1ProgressAt: o.l1Progress, Healthy: healthy, RecipientActive: healthy && o.recipient != (common.Address{}) && o.current.recipientErr == nil && o.current.recipientActive, PayerEntries: len(o.payers), PayerReads: o.activeReads}
89+
for _, entry := range o.payers {
90+
if !entry.valid && entry.failure != nil {
91+
status.PayerFailures++
92+
}
93+
}
94+
return status
7495
}
7596

7697
func (o *PaymentObserver) Snapshot(ctx context.Context) (ChainSnapshot, error) {
@@ -82,9 +103,14 @@ func (o *PaymentObserver) Snapshot(ctx context.Context) (ChainSnapshot, error) {
82103
if err := o.validate(o.current); err != nil {
83104
return ChainSnapshot{}, err
84105
}
85-
s := o.current
86-
s.Block, s.Round, s.CurrentRound = new(big.Int).Set(s.Block), new(big.Int).Set(s.Round), new(big.Int).Set(s.CurrentRound)
87-
return s, nil
106+
return o.current.clone(), nil
107+
}
108+
109+
func (s ChainSnapshot) clone() ChainSnapshot {
110+
for _, value := range []**big.Int{&s.Block, &s.Number, &s.Round, &s.CurrentRound} {
111+
*value = new(big.Int).Set(*value)
112+
}
113+
return s
88114
}
89115

90116
func (s ChainSnapshot) ObservedAt() time.Time {
@@ -106,7 +132,7 @@ func (s ChainSnapshot) Validate() error {
106132
}
107133

108134
func (o *PaymentObserver) validate(s ChainSnapshot) error {
109-
if o.stopped || o.invalid || s.generation != o.generation || o.expired(s, o.l1Progress) {
135+
if o.stopped || o.invalid || (o.lifecycle != nil && o.lifecycle.Err() != nil) || s.generation != o.generation || o.expired(s, o.l1Progress) {
110136
return ErrObservationUnavailable
111137
}
112138
return nil
@@ -117,8 +143,7 @@ func (o *PaymentObserver) expired(s ChainSnapshot, l1Progress time.Time) bool {
117143
return s.observedAt.IsZero() || now.Sub(s.observedAt) >= o.maxAge || now.Sub(s.blockTime) >= o.maxAge || now.Sub(l1Progress) >= o.maxAge
118144
}
119145

120-
// Only Run calls refresh. Previous/current identity is the extension point for
121-
// complete hash-pinned logs or reset; no partial delta authorizes publication.
146+
// Only Run calls refresh.
122147
func (o *PaymentObserver) refresh(ctx context.Context) error {
123148
at := o.now()
124149
head, err := o.chain.Contracts.RPC.header(ctx, "latest")
@@ -128,7 +153,7 @@ func (o *PaymentObserver) refresh(ctx context.Context) error {
128153
o.mu.Lock()
129154
o.contact = o.now()
130155
prior := o.header
131-
gap := false
156+
gap, continuous := false, false
132157
if head.Hash == (common.Hash{}) || head.Number == nil {
133158
o.mu.Unlock()
134159
return ErrObservationUnavailable
@@ -142,6 +167,7 @@ func (o *PaymentObserver) refresh(ctx context.Context) error {
142167
return ErrObservationUnavailable
143168
}
144169
gap = head.Hash != prior.Hash && distance.Cmp(big.NewInt(1)) > 0
170+
continuous = distance.Cmp(big.NewInt(1)) == 0 && head.ParentHash == prior.Hash
145171
if head.Hash != prior.Hash && !gap && (distance.Sign() == 0 || head.ParentHash != prior.Hash) {
146172
o.invalid = true
147173
o.generation++
@@ -171,7 +197,8 @@ func (o *PaymentObserver) refresh(ctx context.Context) error {
171197
// A polling gap does not itself orphan the retained observation. Prove
172198
// its anchor before keeping it available during the pinned backfill.
173199
anchor, err := o.chain.Contracts.RPC.header(ctx, hexutil.EncodeBig((*big.Int)(prior.Number)))
174-
if err != nil || anchor.Hash != prior.Hash || anchor.Number == nil || (*big.Int)(anchor.Number).Cmp((*big.Int)(prior.Number)) != 0 {
200+
continuous = err == nil && anchor.Hash == prior.Hash && anchor.Number != nil && (*big.Int)(anchor.Number).Cmp((*big.Int)(prior.Number)) == 0
201+
if !continuous {
175202
o.mu.Lock()
176203
o.invalid = true
177204
o.generation++
@@ -193,6 +220,19 @@ func (o *PaymentObserver) refresh(ctx context.Context) error {
193220
if err := ctx.Err(); err != nil {
194221
return err
195222
}
223+
changed, reset := o.payerChanges(ctx, prior, head, s, continuous)
224+
if gap && reset {
225+
o.invalidate()
226+
}
227+
// Hash-pinned logs can outlive their canonical block, even on a reset.
228+
canonical, err := o.chain.Contracts.RPC.header(ctx, hexutil.EncodeBig((*big.Int)(head.Number)))
229+
if err != nil || canonical.Hash != head.Hash {
230+
o.invalidate()
231+
return ErrObservationUnavailable
232+
}
233+
if err := ctx.Err(); err != nil {
234+
return err
235+
}
196236
o.mu.Lock()
197237
defer o.mu.Unlock()
198238
progress, l1Progress, highWater := o.progress, o.l1Progress, o.l1HighWater
@@ -206,6 +246,12 @@ func (o *PaymentObserver) refresh(ctx context.Context) error {
206246
if o.stopped || o.expired(s, l1Progress) {
207247
return ErrObservationUnavailable
208248
}
249+
for key, entry := range o.payers {
250+
if _, affected := changed[key.payer]; reset || affected {
251+
entry.version++
252+
entry.valid, entry.failure = false, nil
253+
}
254+
}
209255
o.current, o.header, o.invalid = s, head, false
210256
o.progress, o.l1Progress, o.l1HighWater = progress, l1Progress, highWater
211257
o.requireL1 = o.requireL1 || head.L1BlockNumber != nil

‎eth/payment_observer_test.go‎

Lines changed: 23 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ func newTestObserver(t *testing.T) (*test.ChainRPC, *PaymentObserver, *time.Time
2626
c, err := NewContracts(rpc, f.Controller)
2727
require.NoError(t, err)
2828
o := NewPaymentObserver(PaymentChain{Contracts: c}, true, common.Address{})
29+
o.lifecycle = t.Context()
2930
now := time.Now().Truncate(time.Second)
3031
o.now = func() time.Time { return now }
3132
return f, o, &now
@@ -36,6 +37,7 @@ func advanceObserver(f *test.ChainRPC, now time.Time) {
3637
s.Parent, s.Number, s.Timestamp = s.Hash, s.Number+1, uint64(now.Unix())
3738
s.Hash = common.BigToHash(new(big.Int).SetUint64(s.Number))
3839
s.L1Block++
40+
s.Logs, s.LogsBloom = nil, nil
3941
})
4042
}
4143

@@ -202,23 +204,27 @@ func TestObserverL1ProgressDeadline(t *testing.T) {
202204
}
203205

204206
func TestObserverExpiredCandidateIsNotPublished(t *testing.T) {
205-
f, o, now := newTestObserver(t)
206-
require.NoError(t, o.refresh(t.Context()))
207-
old := o.Status()
208-
advanceObserver(f, *now)
209-
f.Update(func(s *test.ChainState) {
210-
s.Before = func(_ context.Context, name string) {
211-
if name == "RoundsManager.currentRound" {
212-
*now = now.Add(30 * time.Second)
213-
}
214-
}
215-
})
216-
require.ErrorIs(t, o.refresh(t.Context()), ErrObservationUnavailable)
217-
status := o.Status()
218-
require.Equal(t, old.ObservedAt, status.ObservedAt)
219-
require.Equal(t, old.HeadProgressAt, status.HeadProgressAt)
220-
require.Equal(t, old.L1ProgressAt, status.L1ProgressAt)
221-
require.Equal(t, int64(50), o.current.Block.Int64())
207+
for _, phase := range []string{"RoundsManager.currentRound", "eth_getLogs"} {
208+
t.Run(phase, func(t *testing.T) {
209+
f, o, now := newTestObserver(t)
210+
require.NoError(t, o.refresh(t.Context()))
211+
old := o.Status()
212+
advanceObserver(f, *now)
213+
f.Update(func(s *test.ChainState) {
214+
s.Before = func(_ context.Context, name string) {
215+
if name == phase {
216+
*now = now.Add(30 * time.Second)
217+
}
218+
}
219+
})
220+
require.ErrorIs(t, o.refresh(t.Context()), ErrObservationUnavailable)
221+
status := o.Status()
222+
require.Equal(t, old.ObservedAt, status.ObservedAt)
223+
require.Equal(t, old.HeadProgressAt, status.HeadProgressAt)
224+
require.Equal(t, old.L1ProgressAt, status.L1ProgressAt)
225+
require.Equal(t, int64(50), o.current.Block.Int64())
226+
})
227+
}
222228
}
223229

224230
func TestObserverPinnedBackfillAndReorg(t *testing.T) {

‎eth/payment_test.go‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -168,16 +168,20 @@ func TestRedemptionReceiptRequiresCanonicalFinality(t *testing.T) {
168168
require.NoError(t, err)
169169
defer rpc.Close()
170170
contracts := &Contracts{RPC: rpc}
171-
confirmed, reverted, err := (PaymentChain{Contracts: contracts}).Receipt(t.Context(), ethcommon.HexToHash("0x1234"))
171+
receipt, err := (PaymentChain{Contracts: contracts}).FinalizedReceipt(t.Context(), ethcommon.HexToHash("0x1234"))
172172
if strings.HasPrefix(scenario, "invalid") {
173173
require.ErrorContains(t, err, "invalid transaction receipt")
174174
_, err = contracts.WaitReceipt(t.Context(), ethcommon.HexToHash("0x1234"))
175175
require.ErrorContains(t, err, "invalid transaction receipt")
176176
} else {
177177
require.NoError(t, err)
178178
}
179-
require.Equal(t, scenario == "confirmed", confirmed)
180-
require.Equal(t, scenario == "reverted", reverted)
179+
require.Equal(t, scenario == "confirmed", receipt != nil && receipt.Status == types.ReceiptStatusSuccessful)
180+
require.Equal(t, scenario == "reverted", receipt != nil && receipt.Status == types.ReceiptStatusFailed)
181+
if receipt != nil {
182+
require.Equal(t, big.NewInt(16), receipt.BlockNumber)
183+
require.Equal(t, hash, receipt.BlockHash.Hex())
184+
}
181185
})
182186
}
183187
}

‎eth/rpc.go‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -226,6 +226,7 @@ type miniHeader struct {
226226
Hash ethcommon.Hash `json:"hash"`
227227
ParentHash ethcommon.Hash `json:"parentHash"`
228228
Timestamp *hexutil.Uint64 `json:"timestamp"`
229+
LogsBloom *types.Bloom `json:"logsBloom"`
229230
}
230231

231232
func (r *RPC) header(ctx context.Context, block any) (*miniHeader, error) {

0 commit comments

Comments
 (0)