github.com/ethersphere/bee/v2@v2.2.0/pkg/postage/interface.go (about)

     1  // Copyright 2020 The Swarm Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  package postage
     6  
     7  import (
     8  	"context"
     9  	"io"
    10  	"math/big"
    11  
    12  	"github.com/ethereum/go-ethereum/common"
    13  	"github.com/ethereum/go-ethereum/core/types"
    14  )
    15  
    16  // EventUpdater interface definitions reflect the updates triggered by events
    17  // emitted by the postage contract on the blockchain.
    18  type EventUpdater interface {
    19  	Create(id []byte, owner []byte, totalAmount, normalisedBalance *big.Int, depth, bucketDepth uint8, immutable bool, txHash common.Hash) error
    20  	TopUp(id []byte, topUpAmount, normalisedBalance *big.Int, txHash common.Hash) error
    21  	UpdateDepth(id []byte, depth uint8, normalisedBalance *big.Int, txHash common.Hash) error
    22  	UpdatePrice(price *big.Int, txHash common.Hash) error
    23  	UpdateBlockNumber(blockNumber uint64) error
    24  	Start(ctx context.Context, startBlock uint64, initState *ChainSnapshot) error
    25  
    26  	TransactionStart() error
    27  	TransactionEnd() error
    28  }
    29  
    30  // ChainSnapshot represents the snapshot of all the postage events between the
    31  // FirstBlockNumber and LastBlockNumber. The timestamp stores the time at which the
    32  // snapshot was generated. This snapshot can be used to sync the postage package
    33  // to prevent large no. of chain backend calls.
    34  type ChainSnapshot struct {
    35  	Events           []types.Log `json:"events"`
    36  	LastBlockNumber  uint64      `json:"lastBlockNumber"`
    37  	FirstBlockNumber uint64      `json:"firstBlockNumber"`
    38  	Timestamp        int64       `json:"timestamp"`
    39  }
    40  
    41  // Storer represents the persistence layer for batches
    42  // on the current (highest available) block.
    43  type Storer interface {
    44  	ChainStateGetter
    45  
    46  	Radius() uint8
    47  
    48  	// Get returns a batch from the store with the given ID.
    49  	Get([]byte) (*Batch, error)
    50  
    51  	// Exists reports whether batch referenced by the give id exists.
    52  	Exists([]byte) (bool, error)
    53  
    54  	// Iterate iterates through stored batches.
    55  	Iterate(func(*Batch) (bool, error)) error
    56  
    57  	// Save stores given batch in the store. The call is idempotent, so
    58  	// a subsequent call would not create new batches if a batch with
    59  	// such ID already exists.
    60  	Save(*Batch) error
    61  
    62  	// Update updates a given batch in the store by first deleting the
    63  	// existing batch and then creating a new one. It's an error to update
    64  	// non-existing batch.
    65  	Update(*Batch, *big.Int, uint8) error
    66  
    67  	// PutChainState puts given chain state into the store.
    68  	PutChainState(*ChainState) error
    69  
    70  	// Reset resets chain state and reserve state of the storage.
    71  	Reset() error
    72  
    73  	SetBatchExpiryHandler(BatchExpiryHandler)
    74  }
    75  
    76  // StorageRadiusSetter is used to calculate total batch commitment of the network.
    77  type CommitmentGetter interface {
    78  	Commitment() (uint64, error)
    79  }
    80  
    81  type ChainStateGetter interface {
    82  	CommitmentGetter
    83  	// GetChainState returns the stored chain state from the store.
    84  	GetChainState() *ChainState
    85  }
    86  
    87  // Listener provides a blockchain event iterator.
    88  type Listener interface {
    89  	io.Closer
    90  	Listen(ctx context.Context, from uint64, updater EventUpdater, initState *ChainSnapshot) <-chan error
    91  }
    92  
    93  type BatchEventListener interface {
    94  	HandleCreate(*Batch, *big.Int) error
    95  	HandleTopUp(id []byte, newBalance *big.Int)
    96  	HandleDepthIncrease(id []byte, newDepth uint8)
    97  }
    98  
    99  type BatchExpiryHandler interface {
   100  	HandleStampExpiry(context.Context, []byte) error
   101  }