sequencing

README

go-sequencing

go-sequencing defines a generic sequencing interface for modular blockchains

Sequencing Interface

Method	Params	Return
SubmitRollupTransaction	context.Context, rollupId RollupId, tx Tx	error
GetNextBatch	context.Context, lastBatchHash Hash	batch Batch, timestamp Time error
VerifyBatch	context.Context, batchHash Hash	success bool, error

Note: Batch is []Tx and Tx is []byte. Also Hash and RollupId are []byte.

Implementations

The following implementations are available:

• centralized-sequencer implements a centralized sequencer that posts rollup transactions to Celestia DA.
• astria-sequencer implements a Astria sequencer middleware that connects to Astria shared sequencer.

In addition the following helper implementations are available:

• DummySequencer implements a Mock sequencer useful for testing.
• Proxy implements a proxy server that forwards requests to a gRPC server. The proxy client can be used directly to interact with the sequencer service.

Helpful commands

# Generate protobuf files. Requires docker.
make proto-gen

# Lint protobuf files. Requires docker.
make proto-lint

# Run tests.
make test

# Run linters (requires golangci-lint, markdownlint, hadolint, and yamllint)
make lint

Local Sequencer

In this repo there is a mock local-sequencer server that implements the go-sequencing interface. This server is useful for testing and development purposes.

Running the local sequencer binary

To run the mock local-sequencer server, run the following command:

make build

This will build the local-sequencer binary. To run the server, run:

./build/local-sequencer

You will see an output like the following:

2024/11/13 10:56:01 Listening on: localhost:50051

Running the local sequencer in Docker

To run the mock local-sequencer server in Docker, run the following command:

make docker-build

This will build a local-sequencer Docker image. To run the server, run:

docker run -p 50051:50051 --rm local-sequencer

In order to connect your rollup to your local sequencer, you need to pass in the rollup ID by using the following command:

docker run -p 50051:50051 --rm local-sequencer -listen-all -rollup-id=testing

Contributing

We welcome your contributions! Everyone is welcome to contribute, whether it's in the form of code, documentation, bug reports, feature requests, or anything else.

If you're looking for issues to work on, try looking at the good first issue list. Issues with this tag are suitable for a new external contributor and is a great way to find something you can help with!

Please join our Community Discord to ask questions, discuss your ideas, and connect with other contributors.

Code of Conduct

See our Code of Conduct here.

Documentation

Index

• type Batch
  • func (batch *Batch) FromProto(pb *pbseq.Batch)
  • func (batch *Batch) Hash() ([]byte, error)
  • func (batch *Batch) Marshal() ([]byte, error)
  • func (batch *Batch) ToProto() *pbseq.Batch
  • func (batch *Batch) Unmarshal(data []byte) error
• type BatchVerifier
• type GetNextBatchRequest
• type GetNextBatchResponse
• type Hash
• type RollupId
• type Sequencer
• type SequencerInput
• type SequencerOutput
• type SubmitRollupTransactionRequest
• type SubmitRollupTransactionResponse
• type Tx
• type VerifyBatchRequest
• type VerifyBatchResponse

Types

type Batch

type Batch struct {
	Transactions []Tx
}

Batch is a collection of transactions

func (*Batch) FromProto

func (batch *Batch) FromProto(pb *pbseq.Batch)

FromProto deserializes a batch from a protobuf message.

func (*Batch) Hash

func (batch *Batch) Hash() ([]byte, error)

Hash returns the hash of a batch.

func (*Batch) Marshal

func (batch *Batch) Marshal() ([]byte, error)

Marshal serializes a batch to a byte slice.

func (*Batch) ToProto

func (batch *Batch) ToProto() *pbseq.Batch

ToProto serializes a batch to a protobuf message.

func (*Batch) Unmarshal

func (batch *Batch) Unmarshal(data []byte) error

Unmarshal deserializes a batch from a byte slice.

type BatchVerifier

type BatchVerifier interface {
	// VerifyBatch verifies a batch of transactions received from the sequencer
	// RollupId is the unique identifier for the rollup chain
	// BatchHash is the cryptographic hash of the batch to verify
	// returns a boolean indicating if the batch is valid and an error if any from the sequencer
	VerifyBatch(ctx context.Context, req VerifyBatchRequest) (*VerifyBatchResponse, error)
}

BatchVerifier provides a method for verifying a batch of transactions received from the sequencer

type GetNextBatchRequest

type GetNextBatchRequest struct {
	RollupId      RollupId
	LastBatchHash Hash
	MaxBytes      uint64
}

GetNextBatchRequest is a request to get the next batch of transactions from sequencer to rollup

type GetNextBatchResponse

type GetNextBatchResponse struct {
	Batch     *Batch
	Timestamp time.Time
}

GetNextBatchResponse is a response to getting the next batch of transactions from sequencer to rollup

type Hash

type Hash = []byte

Hash is a cryptographic hash of the Batch

type RollupId

type RollupId = []byte

RollupId is a unique identifier for a rollup chain

type Sequencer

type Sequencer interface {
	SequencerInput
	SequencerOutput
	BatchVerifier
}

Sequencer is a generic interface for a rollup sequencer

type SequencerInput

type SequencerInput interface {
	// SubmitRollupTransaction submits a transaction from rollup to sequencer
	// RollupId is the unique identifier for the rollup chain
	// Tx is the transaction to submit
	// returns an error if any from the sequencer
	SubmitRollupTransaction(ctx context.Context, req SubmitRollupTransactionRequest) (*SubmitRollupTransactionResponse, error)
}

SequencerInput provides a method for submitting a transaction from rollup to sequencer

type SequencerOutput

type SequencerOutput interface {
	// GetNextBatch returns the next batch of transactions from sequencer to rollup
	// RollupId is the unique identifier for the rollup chain
	// LastBatchHash is the cryptographic hash of the last batch received by the rollup
	// MaxBytes is the maximum number of bytes to return in the batch
	// returns the next batch of transactions and an error if any from the sequencer
	GetNextBatch(ctx context.Context, req GetNextBatchRequest) (*GetNextBatchResponse, error)
}

SequencerOutput provides a method for getting the next batch of transactions from sequencer to rollup

type SubmitRollupTransactionRequest

type SubmitRollupTransactionRequest struct {
	RollupId RollupId
	Tx       Tx
}

SubmitRollupTransactionRequest is a request to submit a transaction from rollup to sequencer

type SubmitRollupTransactionResponse

type SubmitRollupTransactionResponse struct {
}

SubmitRollupTransactionResponse is a response to submitting a transaction from rollup to sequencer

type Tx

type Tx = []byte

Tx is a rollup transaction

type VerifyBatchRequest

type VerifyBatchRequest struct {
	RollupId  RollupId
	BatchHash Hash
}

VerifyBatchRequest is a request to verify a batch of transactions received from the sequencer

type VerifyBatchResponse

type VerifyBatchResponse struct {
	Status bool
}

VerifyBatchResponse is a response to verifying a batch of transactions received from the sequencer