plasma

package
v1.4.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 23, 2024 License: MIT Imports: 20 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	EnabledFlagName         = "plasma.enabled"
	DaServerAddressFlagName = "plasma.da-server"
	VerifyOnReadFlagName    = "plasma.verify-on-read"
)
View Source 
const MaxInputSize = 130672

Max input size ensures the canonical chain cannot include input batches too large to challenge in the Data Availability Challenge contract. Value in number of bytes. This value can only be changed in a hard fork.

View Source 
const TxDataVersion1 = 1

TxDataVersion1 is the version number for batcher transactions containing plasma commitments. It should not collide with DerivationVersion which is still used downstream when parsing the frames.

Variables

View Source 
var (
	ChallengeStatusEventName    = "ChallengeStatusChanged"
	ChallengeStatusEventABI     = "ChallengeStatusChanged(uint256,bytes,uint8)"
	ChallengeStatusEventABIHash = crypto.Keccak256Hash([]byte(ChallengeStatusEventABI))
)
View Source 
var Disabled = &PlasmaDisabled{}
View Source 
var ErrCommitmentMismatch = errors.New("commitment mismatch")

ErrCommitmentMismatch is returned when the commitment does not match the given input.

View Source 
var ErrExpiredChallenge = errors.New("challenge expired")

ErrExpiredChallenge is returned when a challenge was not resolved and derivation should skip this input.

View Source 
var ErrInvalidChallenge = errors.New("invalid challenge")

ErrInvalidChallenge is returned when a challenge event does is decoded but does not relate to the actual chain commitments.

View Source 
var ErrInvalidCommitment = errors.New("invalid commitment")

ErrInvalidCommitment is returned when the commitment cannot be parsed into a known commitment type.

View Source 
var ErrInvalidInput = errors.New("invalid input")

ErrInvalidInput is returned when the input is not valid for posting to the DA storage.

View Source 
var ErrMissingPastWindow = errors.New("data missing past window")

ErrMissingPastWindow is returned when the input data is MIA and cannot be challenged. This is a protocol fatal error.

View Source 
var ErrNotEnabled = errors.New("plasma not enabled")
View Source 
var ErrNotFound = errors.New("not found")

ErrNotFound is returned when the server could not find the input.

View Source 
var ErrPendingChallenge = errors.New("not found, pending challenge")

ErrPendingChallenge is returned when data is not available but can still be challenged/resolved so derivation should halt temporarily.

View Source 
var ErrReorgRequired = errors.New("reorg required")

ErrReorgRequired is returned when a commitment was derived but for which the challenge expired. This requires a reorg to rederive without the input even if the input was previously available.

Functions

func CLIFlags 

func CLIFlags(envPrefix string, category string) []cli.Flag

func DecodeChallengeStatusEvent 

func DecodeChallengeStatusEvent(log *types.Log) (*bindings.DataAvailabilityChallengeChallengeStatusChanged, error)

DecodeChallengeStatusEvent decodes the challenge status event from the log data and the indexed challenged hash and block number from the topics.

func DecodeResolvedInput 

func DecodeResolvedInput(data []byte) ([]byte, error)

DecodeResolvedInput decodes the preimage bytes from the tx input data.

Types

type CLIConfig 

type CLIConfig struct {
	Enabled      bool
	DAServerURL  string
	VerifyOnRead bool
}

func ReadCLIConfig 

func ReadCLIConfig(c *cli.Context) CLIConfig

func (CLIConfig) Check 

func (c CLIConfig) Check() error

func (CLIConfig) NewDAClient 

func (c CLIConfig) NewDAClient() *DAClient

type ChallengeStatus 

type ChallengeStatus uint8
const (
	ChallengeUninitialized ChallengeStatus = iota
	ChallengeActive
	ChallengeResolved
	ChallengeExpired
)

type CommQueue 

type CommQueue []*Commitment

CommQueue is a priority queue of commitments ordered by block number.

func (CommQueue) Len 

func (c CommQueue) Len() int

func (CommQueue) Less 

func (c CommQueue) Less(i, j int) bool

we want the first item in the queue to have the lowest block number

func (*CommQueue) Pop 

func (c *CommQueue) Pop() any

func (*CommQueue) Push 

func (c *CommQueue) Push(x any)

func (CommQueue) Swap 

func (c CommQueue) Swap(i, j int)

type Commitment 

type Commitment struct {
	// contains filtered or unexported fields
}

Commitment keeps track of the onchain state of an input commitment.

type CommitmentType 

type CommitmentType byte

CommitmentType is the commitment type prefix. 

const Keccak256CommitmentType CommitmentType = 0

KeccakCommitmentType is the default commitment type for the DA storage.

type Config 

type Config struct {
	// Required for filtering contract events
	DAChallengeContractAddress common.Address
	// The number of l1 blocks after the input is committed during which one can challenge.
	ChallengeWindow uint64
	// The number of l1 blocks after a commitment is challenged during which one can resolve.
	ResolveWindow uint64
}

Config is the relevant subset of rollup config for plasma DA.

type DA 

type DA struct {
	// contains filtered or unexported fields
}

func NewPlasmaDA 

func NewPlasmaDA(log log.Logger, cli CLIConfig, cfg Config, metrics Metricer) *DA

NewPlasmaDA creates a new PlasmaDA instance with the given log and CLIConfig.

func NewPlasmaDAWithState 

func NewPlasmaDAWithState(log log.Logger, cfg Config, storage DAStorage, metrics Metricer, state *State) *DA

NewPlasmaWithState creates a plasma storage from initial state used for testing in isolation. We pass the L1Fetcher to each method so it is kept in sync with the conf depth of the pipeline.

func NewPlasmaDAWithStorage 

func NewPlasmaDAWithStorage(log log.Logger, cfg Config, storage DAStorage, metrics Metricer) *DA

NewPlasmaDAWithStorage creates a new PlasmaDA instance with the given log and DAStorage interface.

func (*DA) AdvanceL1Origin 

func (d *DA) AdvanceL1Origin(ctx context.Context, l1 L1Fetcher, block eth.BlockID) error

AdvanceL1Origin syncs any challenge events included in the l1 block, expires any active challenges after the new resolveWindow, computes and signals the new finalized head and sets the l1 block as the new head for tracking challenges. If forwards an error if any new challenge have expired to trigger a derivation reset.

func (*DA) Finalize 

func (d *DA) Finalize(l1Finalized eth.L1BlockRef)

Finalize takes the L1 finality signal, compares the plasma finalized block and forwards the finality signal to the engine queue based on whichever is most behind.

func (*DA) GetInput 

func (d *DA) GetInput(ctx context.Context, l1 L1Fetcher, comm Keccak256Commitment, blockId eth.BlockID) (eth.Data, error)

GetInput returns the input data for the given commitment bytes. blockNumber is required to lookup the challenge status in the DataAvailabilityChallenge L1 contract.

func (*DA) LoadChallengeEvents 

func (d *DA) LoadChallengeEvents(ctx context.Context, l1 L1Fetcher, block eth.BlockID) error

LoadChallengeEvents fetches the l1 block receipts and updates the challenge status

func (*DA) LookAhead 

func (d *DA) LookAhead(ctx context.Context, l1 L1Fetcher) error

LookAhead increments the challenges origin and process the new block if it exists. It is used when the derivation pipeline stalls due to missing data and we need to continue syncing challenge events until the challenge is resolved or expires.

func (*DA) OnFinalizedHeadSignal 

func (d *DA) OnFinalizedHeadSignal(f HeadSignalFn)

OnFinalizedHeadSignal sets the callback function to be called when the finalized head is updated. This will signal to the engine queue that will set the proper L2 block as finalized.

func (*DA) Reset 

func (d *DA) Reset(ctx context.Context, base eth.L1BlockRef, baseCfg eth.SystemConfig) error

Reset the challenge event derivation origin in case of L1 reorg

type DAClient 

type DAClient struct {
	// contains filtered or unexported fields
}

DAClient is an HTTP client to communicate with a DA storage service. It creates commitments and retrieves input data + verifies if needed. Currently only supports Keccak256 commitments but may be extended eventually.

func NewDAClient 

func NewDAClient(url string, verify bool) *DAClient

func (*DAClient) GetInput 

func (c *DAClient) GetInput(ctx context.Context, comm Keccak256Commitment) ([]byte, error)

GetInput returns the input data for the given encoded commitment bytes.

func (*DAClient) SetInput 

func (c *DAClient) SetInput(ctx context.Context, img []byte) (Keccak256Commitment, error)

SetInput sets the input data and returns the keccak256 hash commitment.

type DAErrFaker 

type DAErrFaker struct {
	Client *MockDAClient
	// contains filtered or unexported fields
}

func (*DAErrFaker) ActGetPreImageFail 

func (f *DAErrFaker) ActGetPreImageFail()

func (*DAErrFaker) ActSetPreImageFail 

func (f *DAErrFaker) ActSetPreImageFail()

func (*DAErrFaker) GetInput 

func (f *DAErrFaker) GetInput(ctx context.Context, key Keccak256Commitment) ([]byte, error)

func (*DAErrFaker) SetInput 

func (f *DAErrFaker) SetInput(ctx context.Context, data []byte) (Keccak256Commitment, error)

type DAStorage 

type DAStorage interface {
	GetInput(ctx context.Context, key Keccak256Commitment) ([]byte, error)
	SetInput(ctx context.Context, img []byte) (Keccak256Commitment, error)
}

DAStorage interface for calling the DA storage server.

type HeadSignalFn 

type HeadSignalFn func(eth.L1BlockRef)

HeadSignalFn is the callback function to accept head-signals without a context.

type Keccak256Commitment 

type Keccak256Commitment []byte

Keccak256Commitment is the default commitment type for op-plasma.

func DecodeKeccak256 

func DecodeKeccak256(commitment []byte) (Keccak256Commitment, error)

DecodeKeccak256 validates and casts the commitment into a Keccak256Commitment.

func Keccak256 

func Keccak256(input []byte) Keccak256Commitment

Keccak256 creates a new commitment from the given input.

func (Keccak256Commitment) Encode 

func (c Keccak256Commitment) Encode() []byte

Encode adds a commitment type prefix self describing the commitment.

func (Keccak256Commitment) TxData 

func (c Keccak256Commitment) TxData() []byte

TxData adds an extra version byte to signal it's a commitment.

func (Keccak256Commitment) Verify 

func (c Keccak256Commitment) Verify(input []byte) error

Verify checks if the commitment matches the given input.

type L1Fetcher 

type L1Fetcher interface {
	InfoAndTxsByHash(ctx context.Context, hash common.Hash) (eth.BlockInfo, types.Transactions, error)
	FetchReceipts(ctx context.Context, blockHash common.Hash) (eth.BlockInfo, types.Receipts, error)
	L1BlockRefByNumber(context.Context, uint64) (eth.L1BlockRef, error)
}

L1Fetcher is the required interface for syncing the DA challenge contract state.

type Metricer 

type Metricer interface {
	RecordActiveChallenge(commBlock uint64, startBlock uint64, hash []byte)
	RecordResolvedChallenge(hash []byte)
	RecordExpiredChallenge(hash []byte)
	RecordChallengesHead(name string, num uint64)
	RecordStorageError()
}

type Metrics 

type Metrics struct {
	ChallengesStatus *prometheus.GaugeVec
	ChallengesHead   *prometheus.GaugeVec

	StorageErrors *metrics.Event
}

func MakeMetrics 

func MakeMetrics(ns string, factory metrics.Factory) *Metrics

func (*Metrics) RecordActiveChallenge 

func (m *Metrics) RecordActiveChallenge(commBlock uint64, startBlock uint64, hash []byte)

RecordActiveChallenge records when a commitment is challenged including the block where the commitment is included, the block where the commitment was challenged and the commitment hash.

func (*Metrics) RecordChallenge 

func (m *Metrics) RecordChallenge(status string)

func (*Metrics) RecordChallengesHead 

func (m *Metrics) RecordChallengesHead(name string, num uint64)

func (*Metrics) RecordExpiredChallenge 

func (m *Metrics) RecordExpiredChallenge(hash []byte)

func (*Metrics) RecordResolvedChallenge 

func (m *Metrics) RecordResolvedChallenge(hash []byte)

func (*Metrics) RecordStorageError 

func (m *Metrics) RecordStorageError()

type MockDAClient 

type MockDAClient struct {
	// contains filtered or unexported fields
}

MockDAClient mocks a DA storage provider to avoid running an HTTP DA server in unit tests.

func NewMockDAClient 

func NewMockDAClient(log log.Logger) *MockDAClient

func (*MockDAClient) DeleteData 

func (c *MockDAClient) DeleteData(key []byte) error

func (*MockDAClient) GetInput 

func (c *MockDAClient) GetInput(ctx context.Context, key Keccak256Commitment) ([]byte, error)

func (*MockDAClient) SetInput 

func (c *MockDAClient) SetInput(ctx context.Context, data []byte) (Keccak256Commitment, error)

type NoopMetrics 

type NoopMetrics struct{}

func (*NoopMetrics) RecordActiveChallenge 

func (m *NoopMetrics) RecordActiveChallenge(commBlock uint64, startBlock uint64, hash []byte)

func (*NoopMetrics) RecordChallengesHead 

func (m *NoopMetrics) RecordChallengesHead(name string, num uint64)

func (*NoopMetrics) RecordExpiredChallenge 

func (m *NoopMetrics) RecordExpiredChallenge(hash []byte)

func (*NoopMetrics) RecordResolvedChallenge 

func (m *NoopMetrics) RecordResolvedChallenge(hash []byte)

func (*NoopMetrics) RecordStorageError 

func (m *NoopMetrics) RecordStorageError()

type PlasmaDisabled 

type PlasmaDisabled struct{}

PlasmaDisabled is a noop plasma DA implementation for stubbing.

func (*PlasmaDisabled) AdvanceL1Origin 

func (d *PlasmaDisabled) AdvanceL1Origin(ctx context.Context, l1 L1Fetcher, blockId eth.BlockID) error

func (*PlasmaDisabled) Finalize 

func (d *PlasmaDisabled) Finalize(ref eth.L1BlockRef)

func (*PlasmaDisabled) GetInput 

func (d *PlasmaDisabled) GetInput(ctx context.Context, l1 L1Fetcher, commitment Keccak256Commitment, blockId eth.BlockID) (eth.Data, error)

func (*PlasmaDisabled) OnFinalizedHeadSignal 

func (d *PlasmaDisabled) OnFinalizedHeadSignal(f HeadSignalFn)

func (*PlasmaDisabled) Reset 

func (d *PlasmaDisabled) Reset(ctx context.Context, base eth.L1BlockRef, baseCfg eth.SystemConfig) error

type State 

type State struct {
	// contains filtered or unexported fields
}

State tracks the commitment and their challenges in order of l1 inclusion.

func NewState 

func NewState(log log.Logger, m Metricer) *State

func (*State) ExpireChallenges 

func (s *State) ExpireChallenges(bn uint64) (uint64, error)

ExpireChallenges walks back from the oldest commitment to find the latest l1 origin for which input data can no longer be challenged. It also marks any active challenges as expired based on the new latest l1 origin. If any active challenges are expired it returns an error to signal that a derivation pipeline reset is required.

func (*State) GetOrTrackChallenge 

func (s *State) GetOrTrackChallenge(key []byte, bn uint64, challengeWindow uint64) *Commitment

GetOrTrackChallenge returns the commitment for the given key if it is already tracked, or initializes a new commitment and adds it to the state.

func (*State) GetResolvedInput 

func (s *State) GetResolvedInput(key []byte) ([]byte, error)

GetResolvedInput returns the input bytes if the commitment was resolved onchain.

func (*State) IsTracking 

func (s *State) IsTracking(key []byte, bn uint64) bool

IsTracking returns whether we currently have a commitment for the given key. if the block number is mismatched we return false to ignore the challenge.

func (*State) Prune 

func (s *State) Prune(bn uint64)

Prune removes commitments once they can no longer be challenged or resolved. the finalized head block number is passed so we can safely remove any commitments with finalized block numbers.

func (*State) Reset 

func (s *State) Reset()

In case of L1 reorg, state should be cleared so we can sync all the challenge events from scratch.

func (*State) SetActiveChallenge 

func (s *State) SetActiveChallenge(key []byte, challengedAt uint64, resolveWindow uint64)

SetActiveChallenge switches the state of a given commitment to active challenge. Noop if the commitment is not tracked as we don't want to track challenges for invalid commitments.

func (*State) SetInputCommitment 

func (s *State) SetInputCommitment(key []byte, committedAt uint64, challengeWindow uint64) *Commitment

SetInputCommitment initializes a new commitment and adds it to the state. This is called when we see a commitment during derivation so we can refer to it later in challenges.

func (*State) SetResolvedChallenge 

func (s *State) SetResolvedChallenge(key []byte, input []byte, resolvedAt uint64)

SetResolvedChallenge switches the state of a given commitment to resolved. Noop if the commitment is not tracked as we don't want to track challenges for invalid commitments. The input posted onchain is stored in the state for later retrieval.

func (*State) TrackDetachedCommitment 

func (s *State) TrackDetachedCommitment(key []byte, bn uint64)

TrackDetachedCommitment is used for indexing challenges for commitments that have not yet been derived due to the derivation pipeline being stalled pending a commitment to be challenged. Memory usage is bound to L1 block space during the DA windows, so it is hard and expensive to spam. Note that the challenge status and expiration is updated separately after it is tracked.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.