plasma

package
v1.7.3 Latest Latest
Warning

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

 Go to latest Published: Apr 8, 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 added in v1.7.2 

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 added in v1.7.2 

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 added in v1.7.2 

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

type CommQueue added in v1.7.2 

type CommQueue []*Commitment

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

func (CommQueue) Len added in v1.7.2 

func (c CommQueue) Len() int

func (CommQueue) Less added in v1.7.2 

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 added in v1.7.2 

func (c *CommQueue) Pop() any

func (*CommQueue) Push added in v1.7.2 

func (c *CommQueue) Push(x any)

func (CommQueue) Swap added in v1.7.2 

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

type Commitment added in v1.7.2 

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

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

type CommitmentType added in v1.7.2 

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 added in v1.7.2 

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 added in v1.7.2 

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 added in v1.7.2 

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 added in v1.7.2 

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 added in v1.7.2 

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 added in v1.7.2 

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 added in v1.7.2 

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 added in v1.7.2 

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 added in v1.7.2 

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 added in v1.7.2 

type HeadSignalFn func(eth.L1BlockRef)

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

type Keccak256Commitment added in v1.7.2 

type Keccak256Commitment []byte

Keccak256Commitment is the default commitment type for op-plasma.

func DecodeKeccak256 added in v1.7.2 

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

DecodeKeccak256 validates and casts the commitment into a Keccak256Commitment.

func Keccak256 added in v1.7.2 

func Keccak256(input []byte) Keccak256Commitment

Keccak256 creates a new commitment from the given input.

func (Keccak256Commitment) Encode added in v1.7.2 

func (c Keccak256Commitment) Encode() []byte

Encode adds a commitment type prefix self describing the commitment.

func (Keccak256Commitment) TxData added in v1.7.2 

func (c Keccak256Commitment) TxData() []byte

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

func (Keccak256Commitment) Verify added in v1.7.2 

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

Verify checks if the commitment matches the given input.

type L1Fetcher added in v1.7.2 

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 added in v1.7.2 

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

type Metrics added in v1.7.2 

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

	StorageErrors *metrics.Event
}

func MakeMetrics added in v1.7.2 

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

func (*Metrics) RecordActiveChallenge added in v1.7.2 

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 added in v1.7.2 

func (m *Metrics) RecordChallenge(status string)

func (*Metrics) RecordChallengesHead added in v1.7.2 

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

func (*Metrics) RecordExpiredChallenge added in v1.7.2 

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

func (*Metrics) RecordResolvedChallenge added in v1.7.2 

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

func (*Metrics) RecordStorageError added in v1.7.2 

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 added in v1.7.2 

type NoopMetrics struct{}

func (*NoopMetrics) RecordActiveChallenge added in v1.7.2 

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

func (*NoopMetrics) RecordChallengesHead added in v1.7.2 

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

func (*NoopMetrics) RecordExpiredChallenge added in v1.7.2 

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

func (*NoopMetrics) RecordResolvedChallenge added in v1.7.2 

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

func (*NoopMetrics) RecordStorageError added in v1.7.2 

func (m *NoopMetrics) RecordStorageError()

type PlasmaDisabled added in v1.7.2 

type PlasmaDisabled struct{}

PlasmaDisabled is a noop plasma DA implementation for stubbing.

func (*PlasmaDisabled) AdvanceL1Origin added in v1.7.2 

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

func (*PlasmaDisabled) Finalize added in v1.7.2 

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

func (*PlasmaDisabled) GetInput added in v1.7.2 

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

func (*PlasmaDisabled) OnFinalizedHeadSignal added in v1.7.2 

func (d *PlasmaDisabled) OnFinalizedHeadSignal(f HeadSignalFn)

func (*PlasmaDisabled) Reset added in v1.7.2 

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

type State added in v1.7.2 

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

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

func NewState added in v1.7.2 

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

func (*State) ExpireChallenges added in v1.7.2 

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 added in v1.7.2 

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 added in v1.7.2 

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

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

func (*State) IsTracking added in v1.7.2 

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 added in v1.7.2 

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 added in v1.7.2 

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 added in v1.7.2 

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 added in v1.7.2 

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 added in v1.7.2 

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 added in v1.7.2 

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.