Feat: eigenda client confirmation depth

api/clients/codecs/blob_codec.go

@@ -6,9 +6,9 @@ import (
 
 type BlobEncodingVersion byte
 
-// All blob encodings are IFFT'd before being dispersed
 const (
-	// This minimal blob encoding includes a version byte, a length uint32, and 31 byte field element mapping.
+	// This minimal blob encoding contains a 32 byte header = [0x00, version byte, uint32 len of data, 0x00, 0x00,...]
+	// followed by the encoded data [0x00, 31 bytes of data, 0x00, 31 bytes of data,...]
 	DefaultBlobEncoding BlobEncodingVersion = 0x0
 )
 
@@ -30,6 +30,9 @@ func GenericDecodeBlob(data []byte) ([]byte, error) {
 	if len(data) <= 32 {
 		return nil, fmt.Errorf("data is not of length greater than 32 bytes: %d", len(data))
 	}
+	// version byte is stored in [1], because [0] is always 0 to ensure the codecBlobHeader is a valid bn254 element
+	// see https://github.com/Layr-Labs/eigenda/blob/master/api/clients/codecs/default_blob_codec.go#L21
+	// TODO: we should prob be working over a struct with methods such as GetBlobEncodingVersion() to prevent index errors
 	version := BlobEncodingVersion(data[1])
 	codec, err := BlobEncodingVersionToCodec(version)
 	if err != nil {
@@ -38,7 +41,7 @@ func GenericDecodeBlob(data []byte) ([]byte, error) {
 
 	data, err = codec.DecodeBlob(data)
 	if err != nil {
-		return nil, err
+		return nil, fmt.Errorf("unable to decode blob: %w", err)
 	}
 
 	return data, nil

api/clients/config.go

@@ -2,28 +2,57 @@ package clients
 
 import (
 	"fmt"
+	"log"
 	"time"
 
 	"github.com/Layr-Labs/eigenda/api/clients/codecs"
 )
 
 type EigenDAClientConfig struct {
-	// RPC is the HTTP provider URL for the Data Availability node.
+	// RPC is the HTTP provider URL for the EigenDA Disperser
 	RPC string
 
-	// The total amount of time that the client will spend waiting for EigenDA to confirm a blob
+	// Timeout used when making dispersals to the EigenDA Disperser
+	// TODO: we should change this param as its name is quite confusing
+	ResponseTimeout time.Duration
+
+	// The total amount of time that the client will spend waiting for EigenDA
+	// to confirm a blob after it has been dispersed
+	// Note that reasonable values for this field will depend on the value of WaitForFinalization.
 	StatusQueryTimeout time.Duration
 
 	// The amount of time to wait between status queries of a newly dispersed blob
 	StatusQueryRetryInterval time.Duration
 
-	// The total amount of time that the client will waiting for a response from the EigenDA disperser
-	ResponseTimeout time.Duration
+	// The Ethereum RPC URL to use for querying the Ethereum blockchain.
+	// This is used to make sure that the blob has been confirmed on-chain.
+	// Only needed when WaitForConfirmationDepth > 0.
+	EthRpcUrl string
+
+	// The address of the EigenDAServiceManager contract, used to make sure that the blob has been confirmed on-chain.
+	// Only needed when WaitForConfirmationDepth > 0.
+	SvcManagerAddr string
+
+	// The number of Ethereum blocks to wait after the blob's batch has been included onchain, before returning from PutBlob calls.
+	// Only makes sense to wait for < 24 blocks (2 epochs). Otherwise, use WaitForFinalization instead.
+	//
+	// When WaitForFinalization is true, this field is ignored.
+	// 
+	// If WaitForConfirmationDepth > 0, then EthRpcUrl and SvcManagerAddr must be set.
+	WaitForConfirmationDepth uint64
+
+	// If true, will wait for the blob to finalize, if false, will wait only for the blob to confirm.
+	WaitForFinalization bool
 
 	// The quorum IDs to write blobs to using this client. Should not include default quorums 0 or 1.
+	// TODO: should we change this to core.QuorumID instead? https://github.com/Layr-Labs/eigenda/blob/style--improve-api-clients-comments/core/data.go#L18
 	CustomQuorumIDs []uint
 
-	// Signer private key in hex encoded format. This key should not be associated with an Ethereum address holding any funds.
+	// Signer private key in hex encoded format. This key is currently purely used for authn/authz on the disperser.
+	// For security, it should not be associated with an Ethereum address holding any funds.
+	// This might change once we introduce payments.
+	// OPTIONAL: this value is optional, and if set to "", will result in a read-only eigenDA client,
+	// that can retrieve blobs but cannot disperse blobs.
 	SignerPrivateKeyHex string
 
 	// Whether to disable TLS for an insecure connection when connecting to a local EigenDA disperser instance.
@@ -37,12 +66,29 @@ type EigenDAClientConfig struct {
 	// the commitment. With this mode disabled, you will need to supply the entire blob to perform a verification
 	// that any part of the data matches the KZG commitment.
 	DisablePointVerificationMode bool
-
-	// If true, will wait for the blob to finalize, if false, will wait only for the blob to confirm.
-	WaitForFinalization bool
 }
 
 func (c *EigenDAClientConfig) CheckAndSetDefaults() error {
+	if c.WaitForFinalization {
+		if c.WaitForConfirmationDepth != 0 {
+			log.Println("Warning: WaitForFinalization is set to true, WaitForConfirmationDepth will be ignored")
+		}
+	} else {
+		if c.WaitForConfirmationDepth > 24 {
+			log.Printf("Warning: WaitForConfirmationDepth is set to %v > 24 (2 epochs == finality). Consider setting WaitForFinalization to true instead.\n", c.WaitForConfirmationDepth)
+		}
+	}
+	if c.WaitForConfirmationDepth > 0 {
+		if c.SvcManagerAddr == "" {
+			return fmt.Errorf("EigenDAClientConfig.SvcManagerAddr not set. Needed because WaitForConfirmationDepth > 0")
+		}
+		if c.EthRpcUrl == "" {
+			return fmt.Errorf("EigenDAClientConfig.EthRpcUrl not set. Needed because WaitForConfirmationDepth > 0")
+		}
+	}
+	if c.SvcManagerAddr == "" && c.WaitForConfirmationDepth > 0 {
+		return fmt.Errorf("EigenDAClientConfig.SvcManagerAddr not set. Needed because WaitForConfirmationDepth > 0")
+	}
 	if c.StatusQueryRetryInterval == 0 {
 		c.StatusQueryRetryInterval = 5 * time.Second
 	}

api/clients/disperser_client.go

@@ -20,6 +20,9 @@ import (
 type Config struct {
 	Hostname          string
 	Port              string
+	// BlobDispersal Timeouts for both authenticated and unauthenticated dispersals
+	// GetBlobStatus and RetrieveBlob timeouts are hardcoded to 60seconds
+	// TODO: do we want to add config timeouts for those separate requests?
 	Timeout           time.Duration
 	UseSecureGrpcFlag bool
 }