refactor(fibre): BlobId

Author: Wondertan

fibre/blob.go

@@ -2,7 +2,6 @@ package fibre
 
 import (
 	"encoding/binary"
-	"encoding/hex"
 	"errors"
 	"fmt"
 	"runtime"
@@ -19,42 +18,6 @@ var (
 	ErrBlobCommitmentMismatch = errors.New("commitment mismatch: reconstructed data doesn't match expected commitment")
 )
 
-// Commitment is a commitment to a blob.
-// TODO(@Wondertan): merge with rsema1d.Commitment once it has these methods.
-type Commitment rsema1d.Commitment
-
-// UnmarshalBinary decodes a [Commitment] from bytes.
-func (c *Commitment) UnmarshalBinary(data []byte) error {
-	if len(data) != 32 {
-		return fmt.Errorf("commitment must be 32 bytes, got %d", len(data))
-	}
-	copy(c[:], data)
-	return nil
-}
-
-// String returns the hex-encoded string representation of the commitment.
-func (c Commitment) String() string {
-	return hex.EncodeToString(c[:])
-}
-
-// CommitmentFromString decodes a [Commitment] from a hex-encoded string.
-func CommitmentFromString(s string) (Commitment, error) {
-	data, err := hex.DecodeString(s)
-	if err != nil {
-		return Commitment{}, fmt.Errorf("decoding hex: %w", err)
-	}
-	var c Commitment
-	if err := c.UnmarshalBinary(data); err != nil {
-		return Commitment{}, err
-	}
-	return c, nil
-}
-
-// Equals returns true if the two commitments are equal.
-func (c Commitment) Equals(other Commitment) bool {
-	return c == other
-}
-
 // BlobConfig contains configuration parameters for blob encoding and decoding.
 type BlobConfig struct {
 	// BlobVersion is the version of the row format.
@@ -77,6 +40,17 @@ func DefaultBlobConfigV0() BlobConfig {
 	return NewBlobConfigFromParams(0, DefaultProtocolParams)
 }
 
+// BlobConfigForVersion returns the [BlobConfig] for the given blob version.
+// Returns an error if the version is not supported.
+func BlobConfigForVersion(version uint8) (BlobConfig, error) {
+	switch version {
+	case 0:
+		return DefaultBlobConfigV0(), nil
+	default:
+		return BlobConfig{}, fmt.Errorf("unsupported blob version: %d", version)
+	}
+}
+
 // NewBlobConfigFromParams creates a [BlobConfig] with values derived from the given [ProtocolParams].
 // Use this when you need a config with non-default protocol parameters (e.g., for testing).
 func NewBlobConfigFromParams(blobVersion uint8, p ProtocolParams) BlobConfig {
@@ -115,7 +89,7 @@ type Blob struct {
 	cfg BlobConfig
 
 	extendedData *rsema1d.ExtendedData
-	commitment   Commitment
+	id           BlobID
 	rlcCoeffs    []field.GF128
 
 	// holds meta fields about the blob
@@ -146,7 +120,8 @@ func NewBlob(data []byte, cfg BlobConfig) (d *Blob, err error) {
 	}
 
 	rows := d.header.encodeToRows(data, cfg)
-	d.extendedData, d.commitment, d.rlcCoeffs, err = rsema1d.Encode(rows, &rsema1d.Config{
+	var rsemaCommitment rsema1d.Commitment
+	d.extendedData, rsemaCommitment, d.rlcCoeffs, err = rsema1d.Encode(rows, &rsema1d.Config{
 		K:           cfg.OriginalRows,
 		N:           cfg.ParityRows,
 		RowSize:     len(rows[0]),
@@ -155,23 +130,32 @@ func NewBlob(data []byte, cfg BlobConfig) (d *Blob, err error) {
 	if err != nil {
 		return nil, fmt.Errorf("encoding data: %w", err)
 	}
+	d.id = NewBlobID(cfg.BlobVersion, rsemaCommitment)
 
 	return d, nil
 }
 
 // NewEmptyBlob creates a new [Blob] instance for receiving and reconstructing data.
-func NewEmptyBlob(cfg BlobConfig, commitment Commitment) *Blob {
+// Returns an error if the BlobID is invalid or the blob version is not supported.
+func NewEmptyBlob(id BlobID) (*Blob, error) {
+	if err := id.Validate(); err != nil {
+		return nil, fmt.Errorf("invalid blob ID: %w", err)
+	}
+	cfg, err := BlobConfigForVersion(id.Version())
+	if err != nil {
+		return nil, err
+	}
 	totalRows := cfg.OriginalRows + cfg.ParityRows
 	return &Blob{
-		cfg:        cfg,
-		commitment: commitment,
-		rows:       make([][]byte, totalRows),
-	}
+		cfg:  cfg,
+		id:   id,
+		rows: make([][]byte, totalRows),
+	}, nil
 }
 
-// Commitment returns the commitment to the blob.
-func (d *Blob) Commitment() Commitment {
-	return d.commitment
+// ID returns the BlobID of this blob.
+func (d *Blob) ID() BlobID {
+	return d.id
 }
 
 // Config returns the blob's configuration.
@@ -220,14 +204,13 @@ func (d *Blob) Row(index int) (*rsema1d.RowInclusionProof, error) {
 // SetRow adds and verifies [*rsema1d.RowInclusionProof] to the blob.
 // It is safe to call this method concurrently only for disjoint indices.
 func (d *Blob) SetRow(row *rsema1d.RowInclusionProof) error {
-	// verify the inclusion proof
 	config := &rsema1d.Config{
 		K:           d.cfg.OriginalRows,
 		N:           d.cfg.ParityRows,
 		RowSize:     len(row.Row),
 		WorkerCount: d.cfg.CodingWorkers,
 	}
-	err := rsema1d.VerifyRowInclusionProof(row, rsema1d.Commitment(d.commitment), config)
+	err := rsema1d.VerifyRowInclusionProof(row, d.id.Commitment(), config)
 	if err != nil {
 		return fmt.Errorf("verifying row %d: %w", row.Index, err)
 	}
@@ -271,9 +254,9 @@ func (d *Blob) Reconstruct() error {
 	}
 
 	// verify commitment matches
-	if !d.commitment.Equals(Commitment(reconstructedCommitment)) {
-		return fmt.Errorf("%w: expected %s, got %s",
-			ErrBlobCommitmentMismatch, d.commitment.String(), Commitment(reconstructedCommitment).String())
+	if d.id.Commitment() != reconstructedCommitment {
+		return fmt.Errorf("%w: expected %x, got %x",
+			ErrBlobCommitmentMismatch, d.id.Commitment(), reconstructedCommitment[:])
 	}
 
 	// decode header and extract original data from the first K rows, then cache it

fibre/blob_id.go

@@ -0,0 +1,115 @@
+package fibre
+
+import (
+	"bytes"
+	"encoding/hex"
+	"fmt"
+
+	"github.com/celestiaorg/rsema1d"
+)
+
+// CommitmentSize is the size of a Commitment in bytes.
+const CommitmentSize = 32
+
+// Commitment is a 32-byte blob commitment used for protocol messages and storage indexing.
+// TODO: merge with rsema1d.Commitment once that package stabilizes.
+type Commitment rsema1d.Commitment
+
+// String returns the hex-encoded string representation.
+func (c Commitment) String() string {
+	return hex.EncodeToString(c[:])
+}
+
+// UnmarshalBinary decodes a Commitment from bytes.
+func (c *Commitment) UnmarshalBinary(data []byte) error {
+	if len(data) != CommitmentSize {
+		return fmt.Errorf("commitment must be %d bytes, got %d", CommitmentSize, len(data))
+	}
+	copy(c[:], data)
+	return nil
+}
+
+// CommitmentFromString decodes a Commitment from a hex-encoded string.
+func CommitmentFromString(s string) (Commitment, error) {
+	data, err := hex.DecodeString(s)
+	if err != nil {
+		return Commitment{}, fmt.Errorf("decoding hex: %w", err)
+	}
+	if len(data) != CommitmentSize {
+		return Commitment{}, fmt.Errorf("commitment must be %d bytes, got %d", CommitmentSize, len(data))
+	}
+	var c Commitment
+	copy(c[:], data)
+	return c, nil
+}
+
+// BlobIDSize is the size of a BlobID in bytes.
+// Format: [version (1 byte) | Commitment (32 bytes)]
+const BlobIDSize = 33
+
+// BlobID uniquely identifies a blob by combining version and commitment.
+// The first byte encodes the blob version, followed by 32 bytes of commitment.
+// This makes BlobIDs self-describing, allowing clients to know the blob format before downloading.
+type BlobID []byte
+
+// NewBlobID creates a BlobID from version and commitment.
+func NewBlobID(version uint8, commitment Commitment) BlobID {
+	id := make(BlobID, BlobIDSize)
+	id[0] = version
+	copy(id[1:], commitment[:])
+	return id
+}
+
+// Version returns the blob version encoded in this BlobID.
+// Panics if the BlobID is invalid (empty or wrong length).
+func (id BlobID) Version() uint8 {
+	return id[0]
+}
+
+// Validate returns an error if the BlobID is invalid.
+func (id BlobID) Validate() error {
+	if len(id) != BlobIDSize {
+		return fmt.Errorf("blob ID must be %d bytes, got %d", BlobIDSize, len(id))
+	}
+	return nil
+}
+
+// Commitment returns the commitment (without version prefix).
+func (id BlobID) Commitment() Commitment {
+	var c Commitment
+	copy(c[:], id[1:])
+	return c
+}
+
+// UnmarshalBinary decodes a [BlobID] from bytes.
+func (id *BlobID) UnmarshalBinary(data []byte) error {
+	if len(data) != BlobIDSize {
+		return fmt.Errorf("blob ID must be %d bytes, got %d", BlobIDSize, len(data))
+	}
+	*id = make(BlobID, BlobIDSize)
+	copy(*id, data)
+	return nil
+}
+
+// String returns the hex-encoded string representation of the BlobID.
+func (id BlobID) String() string {
+	return hex.EncodeToString(id)
+}
+
+// BlobIDFromString decodes a [BlobID] from a hex-encoded string.
+func BlobIDFromString(s string) (BlobID, error) {
+	data, err := hex.DecodeString(s)
+	if err != nil {
+		return nil, fmt.Errorf("decoding hex: %w", err)
+	}
+	var id BlobID
+	if err := id.UnmarshalBinary(data); err != nil {
+		return nil, err
+	}
+	return id, nil
+}
+
+// Equals returns true if the two BlobIDs are equal.
+func (id BlobID) Equals(other BlobID) bool {
+	return bytes.Equal(id, other)
+}

fibre/blob_test.go

@@ -89,7 +89,8 @@ func TestBlob_Reconstruct(t *testing.T) {
 	}
 
 	testReconstruct := func(t *testing.T, rows []*rsema1d.RowInclusionProof) {
-		reconstructBlob := NewEmptyBlob(cfg, blob.Commitment())
+		reconstructBlob, err := NewEmptyBlob(blob.ID())
+		require.NoError(t, err)
 
 		for _, row := range rows {
 			err = reconstructBlob.SetRow(row)

fibre/client_download.go

@@ -32,18 +32,18 @@ var (
 // Errors:
 //   - [ErrNotFound]: no shard was retrieved for the blob
 //   - [ErrNotEnoughShards]: not enough shards were retrieved to reconstruct the original data
-//   - [ErrInvalidCommitment]: the commitment doesn't match the reconstructed blob
-func (c *Client) Download(ctx context.Context, commitment Commitment) (*Blob, error) {
+//   - [ErrBlobCommitmentMismatch]: the commitment doesn't match the reconstructed blob
+func (c *Client) Download(ctx context.Context, id BlobID) (*Blob, error) {
 	if c.closed.Load() {
 		return nil, ErrClientClosed
 	}
 
 	ctx, span := c.tracer.Start(ctx, "fibre.Client.Download",
-		trace.WithAttributes(attribute.String("blob_commitment", commitment.String())),
+		trace.WithAttributes(attribute.String("blob_commitment", id.Commitment().String())),
 	)
 	defer span.End()
 
-	c.log.DebugContext(ctx, "initiating blob download", "blob_commitment", commitment)
+	c.log.DebugContext(ctx, "initiating blob download", "blob_commitment", id.Commitment())
 
 	// get validator set
 	// TODO(@Wondertan): If we don't want to pass height here, we should at least ensure we handle the case
@@ -59,7 +59,7 @@ func (c *Client) Download(ctx context.Context, commitment Commitment) (*Blob, er
 		attribute.Int64("validator_set_height", int64(valSet.Height)),
 	))
 
-	blob, err := c.downloadBlob(ctx, valSet, commitment)
+	blob, err := c.downloadBlob(ctx, valSet, id)
 	if err != nil {
 		span.RecordError(err)
 		span.SetStatus(codes.Error, "failed to download")
@@ -74,7 +74,7 @@ func (c *Client) Download(ctx context.Context, commitment Commitment) (*Blob, er
 	}
 
 	c.log.DebugContext(ctx, "blob download completed successfully",
-		"blob_commitment", commitment,
+		"blob_commitment", id.Commitment(),
 		"upload_size", blob.UploadSize(),
 		"data_size", blob.DataSize(),
 		"row_size", blob.RowSize(),
@@ -87,14 +87,13 @@ func (c *Client) Download(ctx context.Context, commitment Commitment) (*Blob, er
 	return blob, nil
 }
 
-// downloadFrom downloads a shard for a commitment from a single validator and applies its rows to the blob.
+// downloadFrom downloads a shard for a blob from a single validator and applies its rows to the blob.
 func (c *Client) downloadFrom(
 	ctx context.Context,
 	val *core.Validator,
 	blob *Blob,
 ) error {
-	commitment := blob.Commitment()
-	log := c.log.With("validator", val.Address.String(), "blob_commitment", commitment)
+	log := c.log.With("validator", val.Address.String(), "blob_commitment", blob.ID().Commitment())
 
 	ctx, span := c.tracer.Start(ctx, "download_from",
 		trace.WithAttributes(attribute.String("validator_address", val.Address.String())),
@@ -114,7 +113,7 @@ func (c *Client) downloadFrom(
 	}
 	span.AddEvent("client_acquired")
 
-	resp, err := client.DownloadShard(ctx, &types.DownloadShardRequest{Commitment: commitment[:]})
+	resp, err := client.DownloadShard(ctx, &types.DownloadShardRequest{BlobId: blob.ID()})
 	if err != nil {
 		if context.Cause(ctx) == errDownloaded {
 			span.SetStatus(codes.Ok, "")
@@ -173,12 +172,15 @@ func (c *Client) downloadFrom(
 func (c *Client) downloadBlob(
 	ctx context.Context,
 	valSet validator.Set,
-	commitment Commitment,
+	id BlobID,
 ) (*Blob, error) {
 	ctx, cancel := context.WithCancelCause(ctx)
 	defer cancel(errDownloaded)
 
-	blob := NewEmptyBlob(DefaultBlobConfigV0(), commitment)
+	blob, err := NewEmptyBlob(id)
+	if err != nil {
+		return nil, fmt.Errorf("creating empty blob: %w", err)
+	}
 
 	var (
 		responses            atomic.Uint32         // tracks finished responses