da

README

go-da

go-da defines a generic Data Availability interface for modular blockchains.

DA Interface

Method	Params	Return
MaxBlobSize		uint64
Get	ids []ID, namespace Namespace	[]Blobs
GetIDs	height uint64, namespace Namespace	[]ID
GetProofs	ids []id, namespace Namespace	[]Proof
Commit	blobs []Blob, namespace Namespace	[]Commitment
Validate	ids []Blob, proofs []Proof, namespace Namespace	[]bool
Submit	blobs []Blob, gasPrice float64, namespace Namespace	[]ID

NOTE: The Namespace parameter in the interface methods is optional and used only on DA layers that support the functionality, for example Celestia namespaces and Avail AppIDs.

Implementations

The following implementations are available:

• celestia-da implements Celestia as DA.
• avail-da implements Polygon Avail as DA.

In addition the following helper implementations are available:

• DummyDA implements a Mock DA 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 DA 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

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 Blob
• type Code
• type Commitment
• type DA
• type ErrBlobNotFound
  • func (e *ErrBlobNotFound) Error() string
  • func (e *ErrBlobNotFound) GRPCStatus() *status.Status
• type ErrBlobSizeOverLimit
  • func (e *ErrBlobSizeOverLimit) Error() string
  • func (e *ErrBlobSizeOverLimit) GRPCStatus() *status.Status
• type ErrContextDeadline
  • func (e *ErrContextDeadline) Error() string
  • func (e *ErrContextDeadline) GRPCStatus() *status.Status
• type ErrFutureHeight
  • func (e *ErrFutureHeight) Error() string
  • func (e *ErrFutureHeight) GRPCStatus() *status.Status
• type ErrTxAlreadyInMempool
  • func (e *ErrTxAlreadyInMempool) Error() string
  • func (e *ErrTxAlreadyInMempool) GRPCStatus() *status.Status
• type ErrTxIncorrectAccountSequence
  • func (e *ErrTxIncorrectAccountSequence) Error() string
  • func (e *ErrTxIncorrectAccountSequence) GRPCStatus() *status.Status
• type ErrTxTimedOut
  • func (e *ErrTxTimedOut) Error() string
  • func (e *ErrTxTimedOut) GRPCStatus() *status.Status
• type ErrTxTooLarge
  • func (e *ErrTxTooLarge) Error() string
  • func (e *ErrTxTooLarge) GRPCStatus() *status.Status
• type GetIDsResult
• type ID
• type Namespace
• type Proof

Types

type Blob

type Blob = []byte

Blob is the data submitted/received from DA interface.

type Code

type Code int

Code defines error codes for JSON-RPC.

They are reused for gRPC

const (
	CodeBlobNotFound               Code = 32001
	CodeBlobSizeOverLimit          Code = 32002
	CodeTxTimedOut                 Code = 32003
	CodeTxAlreadyInMempool         Code = 32004
	CodeTxIncorrectAccountSequence Code = 32005
	CodeTxTooLarge                 Code = 32006
	CodeContextDeadline            Code = 32007
	CodeFutureHeight               Code = 32008
)

Codes are used by JSON-RPC client and server

type Commitment

type Commitment = []byte

Commitment should contain serialized cryptographic commitment to Blob value.

type DA

type DA interface {
	// MaxBlobSize returns the max blob size
	MaxBlobSize(ctx context.Context) (uint64, error)

	// Get returns Blob for each given ID, or an error.
	//
	// Error should be returned if ID is not formatted properly, there is no Blob for given ID or any other client-level
	// error occurred (dropped connection, timeout, etc).
	Get(ctx context.Context, ids []ID, namespace Namespace) ([]Blob, error)

	// GetIDs returns IDs of all Blobs located in DA at given height.
	GetIDs(ctx context.Context, height uint64, namespace Namespace) (*GetIDsResult, error)

	// GetProofs returns inclusion Proofs for Blobs specified by their IDs.
	GetProofs(ctx context.Context, ids []ID, namespace Namespace) ([]Proof, error)

	// Commit creates a Commitment for each given Blob.
	Commit(ctx context.Context, blobs []Blob, namespace Namespace) ([]Commitment, error)

	// Submit submits the Blobs to Data Availability layer.
	//
	// This method is synchronous. Upon successful submission to Data Availability layer, it returns the IDs identifying blobs
	// in DA.
	Submit(ctx context.Context, blobs []Blob, gasPrice float64, namespace Namespace) ([]ID, error)

	// SubmitWithOptions submits the Blobs to Data Availability layer.
	//
	// This method is synchronous. Upon successful submission to Data Availability layer, it returns the IDs identifying blobs
	// in DA.
	SubmitWithOptions(ctx context.Context, blobs []Blob, gasPrice float64, namespace Namespace, options []byte) ([]ID, error)

	// Validate validates Commitments against the corresponding Proofs. This should be possible without retrieving the Blobs.
	Validate(ctx context.Context, ids []ID, proofs []Proof, namespace Namespace) ([]bool, error)
}

DA defines very generic interface for interaction with Data Availability layers.

type ErrBlobNotFound

type ErrBlobNotFound struct{}

ErrBlobNotFound is used to indicate that the blob was not found.

func (*ErrBlobNotFound) Error

func (e *ErrBlobNotFound) Error() string

func (*ErrBlobNotFound) GRPCStatus

func (e *ErrBlobNotFound) GRPCStatus() *status.Status

GRPCStatus returns the gRPC status with details for an ErrBlobNotFound error.

type ErrBlobSizeOverLimit

type ErrBlobSizeOverLimit struct{}

ErrBlobSizeOverLimit is used to indicate that the blob size is over limit.

func (*ErrBlobSizeOverLimit) Error

func (e *ErrBlobSizeOverLimit) Error() string

func (*ErrBlobSizeOverLimit) GRPCStatus

func (e *ErrBlobSizeOverLimit) GRPCStatus() *status.Status

GRPCStatus returns the gRPC status with details for an ErrBlobSizeOverLimit error.

type ErrContextDeadline

type ErrContextDeadline struct{}

ErrContextDeadline is the error message returned by the DA when context deadline exceeds.

func (*ErrContextDeadline) Error

func (e *ErrContextDeadline) Error() string

func (*ErrContextDeadline) GRPCStatus

func (e *ErrContextDeadline) GRPCStatus() *status.Status

GRPCStatus returns the gRPC status with details for an ErrContextDeadline error.

type ErrFutureHeight

type ErrFutureHeight struct{}

ErrFutureHeight is returned when requested height is from the future

func (*ErrFutureHeight) Error

func (e *ErrFutureHeight) Error() string

func (*ErrFutureHeight) GRPCStatus

func (e *ErrFutureHeight) GRPCStatus() *status.Status

GRPCStatus returns the gRPC status with details for an ErrFutureHeight error.

type ErrTxAlreadyInMempool

type ErrTxAlreadyInMempool struct{}

ErrTxAlreadyInMempool is the error message returned by the DA when tx is already in mempool.

func (*ErrTxAlreadyInMempool) Error

func (e *ErrTxAlreadyInMempool) Error() string

func (*ErrTxAlreadyInMempool) GRPCStatus

func (e *ErrTxAlreadyInMempool) GRPCStatus() *status.Status

GRPCStatus returns the gRPC status with details for an ErrTxAlreadyInMempool error.

type ErrTxIncorrectAccountSequence

type ErrTxIncorrectAccountSequence struct{}

ErrTxIncorrectAccountSequence is the error message returned by the DA when tx has incorrect sequence.

func (*ErrTxIncorrectAccountSequence) Error

func (e *ErrTxIncorrectAccountSequence) Error() string

func (*ErrTxIncorrectAccountSequence) GRPCStatus

func (e *ErrTxIncorrectAccountSequence) GRPCStatus() *status.Status

GRPCStatus returns the gRPC status with details for an ErrTxIncorrectAccountSequence error.

type ErrTxTimedOut

type ErrTxTimedOut struct{}

ErrTxTimedOut is the error message returned by the DA when mempool is congested.

func (*ErrTxTimedOut) Error

func (e *ErrTxTimedOut) Error() string

func (*ErrTxTimedOut) GRPCStatus

func (e *ErrTxTimedOut) GRPCStatus() *status.Status

GRPCStatus returns the gRPC status with details for an ErrTxTimedOut error.

type ErrTxTooLarge

type ErrTxTooLarge struct{}

ErrTxTooLarge is the err message returned by the DA when tx size is too large.

func (*ErrTxTooLarge) Error

func (e *ErrTxTooLarge) Error() string

func (*ErrTxTooLarge) GRPCStatus

func (e *ErrTxTooLarge) GRPCStatus() *status.Status

GRPCStatus returns the gRPC status with details for an ErrTxTooLarge error.

type GetIDsResult

type GetIDsResult struct {
	IDs       []ID
	Timestamp time.Time
}

GetIDsResult holds the result of GetIDs call: IDs and timestamp of corresponding block.

type ID

type ID = []byte

ID should contain serialized data required by the implementation to find blob in Data Availability layer.

type Namespace

type Namespace = []byte

Namespace is an optional parameter used to set the location a blob should be posted to, for DA layers supporting the functionality.

type Proof

type Proof = []byte

Proof should contain serialized proof of inclusion (publication) of Blob in Data Availability layer.