Controller.md

Controller Configuration

Required Fields

Config	Description
$${\color{red}\texttt{AwsClient.Region}}$$ CONTROLLER_AWS_CLIENT_REGION type: string	Region is the region to use when interacting with S3. Default is "us-east-2".
$${\color{red}\texttt{ChainState.Endpoint}}$$ CONTROLLER_CHAIN_STATE_ENDPOINT type: string	The Graph endpoint
$${\color{red}\texttt{ContractDirectoryAddress}}$$ CONTROLLER_CONTRACT_DIRECTORY_ADDRESS type: string	The contract directory contract address, which is used to derive other EigenDA contract addresses.
$${\color{red}\texttt{DispersalRequestSigner.KeyID}}$$ CONTROLLER_DISPERSAL_REQUEST_SIGNER_KEY_ID type: string	KeyID is the AWS KMS key identifier used for signing requests. Optional if PrivateKey is provided.
$${\color{red}\texttt{DispersalRequestSigner.PrivateKey}}$$ CONTROLLER_DISPERSAL_REQUEST_SIGNER_PRIVATE_KEY type: string	PrivateKey is a hex-encoded private key for local signing (without 0x prefix). Optional if KeyID is provided.
$${\color{red}\texttt{DispersalRequestSigner.Region}}$$ CONTROLLER_DISPERSAL_REQUEST_SIGNER_REGION type: string	Region is the AWS region where the KMS key is located (e.g., "us-east-1"). Required if using KMS.
$${\color{red}\texttt{DisperserID}}$$ CONTROLLER_DISPERSER_ID type: uint32	DisperserID is the unique identifier for this disperser instance.
$${\color{red}\texttt{DynamoDBTableName}}$$ CONTROLLER_DYNAMO_DB_TABLE_NAME type: string	The name of the DynamoDB table used to store "core" metadata (i.e. blob statuses, signatures, etc.).
$${\color{red}\texttt{Encoder.AvailableRelays}}$$ CONTROLLER_ENCODER_AVAILABLE_RELAYS type: []uint32	AvailableRelays is the list of relay keys that can be assigned to blobs. Must not be empty.
$${\color{red}\texttt{Encoder.EncoderAddress}}$$ CONTROLLER_ENCODER_ENCODER_ADDRESS type: string	EncoderAddress is the network address of the encoder service (e.g., "localhost:50051"). Must not be empty.
$${\color{red}\texttt{EthClient.RPCURLs}}$$ CONTROLLER_ETH_CLIENT_RPCURLS type: []string	A list of RPC URL endpoints to connect to the Ethereum chain.
$${\color{red}\texttt{Payment.OnDemand.OnDemandTableName}}$$ CONTROLLER_PAYMENT_ON_DEMAND_ON_DEMAND_TABLE_NAME type: string	The name of the dynamo table where on-demand payment information is stored
$${\color{red}\texttt{Server.GrpcPort}}$$ CONTROLLER_SERVER_GRPC_PORT type: uint16	Port that the gRPC server listens on
$${\color{red}\texttt{SigningRateDynamoDbTableName}}$$ CONTROLLER_SIGNING_RATE_DYNAMO_DB_TABLE_NAME type: string	The name of the DynamoDB table used to store signing rate data.

Optional Fields

Config	Description
$${\color{red}\texttt{AttestationTimeout}}$$ CONTROLLER_ATTESTATION_TIMEOUT type: time.Duration default: 45s	AttestationTimeout is the maximum time to wait for a single node to provide a signature. Must be positive.
$${\color{red}\texttt{AwsClient.AccessKey}}$$ CONTROLLER_AWS_CLIENT_ACCESS_KEY type: string default: ""	AccessKey to use when interacting with S3.
$${\color{red}\texttt{AwsClient.EndpointURL}}$$ CONTROLLER_AWS_CLIENT_ENDPOINT_URL type: string default: ""	EndpointURL of the S3 endpoint to use. If set to "", the AWS library will use the default AWS S3 endpoint.
$${\color{red}\texttt{AwsClient.FragmentParallelismConstant}}$$ CONTROLLER_AWS_CLIENT_FRAGMENT_PARALLELISM_CONSTANT type: int default: 0	This is a deprecated setting and can be ignored.
$${\color{red}\texttt{AwsClient.FragmentParallelismFactor}}$$ CONTROLLER_AWS_CLIENT_FRAGMENT_PARALLELISM_FACTOR type: int default: 8	This is a deprecated setting and can be ignored.
$${\color{red}\texttt{AwsClient.SecretAccessKey}}$$ CONTROLLER_AWS_CLIENT_SECRET_ACCESS_KEY type: string default: ""	SecretAccessKey to use when interacting with S3.
$${\color{red}\texttt{BatchAttestationTimeout}}$$ CONTROLLER_BATCH_ATTESTATION_TIMEOUT type: time.Duration default: 55s	BatchAttestationTimeout is the maximum time to wait for all nodes to provide signatures for a batch. Must be positive and must be longer or equal to the AttestationTimeout.
$${\color{red}\texttt{BatchMetadataUpdatePeriod}}$$ CONTROLLER_BATCH_METADATA_UPDATE_PERIOD type: time.Duration default: 1m0s	BatchMetadataUpdatePeriod is the interval between attempts to refresh batch metadata (reference block number and operator state). Since this changes at most once per eth block, values shorter than 10 seconds are not useful. In practice, checking every several minutes is sufficient. Must be positive.
$${\color{red}\texttt{BlobDispersalQueueSize}}$$ CONTROLLER_BLOB_DISPERSAL_QUEUE_SIZE type: uint32 default: 1024	BlobDispersalQueueSize is the maximum number of blobs that can be queued for dispersal.
$${\color{red}\texttt{BlobDispersalRequestBackoffPeriod}}$$ CONTROLLER_BLOB_DISPERSAL_REQUEST_BACKOFF_PERIOD type: time.Duration default: 50ms	BlobDispersalRequestBackoffPeriod is the delay between fetch attempts when there are no blobs ready for dispersal.
$${\color{red}\texttt{BlobDispersalRequestBatchSize}}$$ CONTROLLER_BLOB_DISPERSAL_REQUEST_BATCH_SIZE type: uint32 default: 32	BlobDispersalRequestBatchSize is the number of blob metadata items to fetch from the store in a single request. Must be at least 1.
$${\color{red}\texttt{ChainState.MaxRetries}}$$ CONTROLLER_CHAIN_STATE_MAX_RETRIES type: int default: 5	The maximum number of retries to pull data from The Graph
$${\color{red}\texttt{ChainState.PullInterval}}$$ CONTROLLER_CHAIN_STATE_PULL_INTERVAL type: time.Duration default: 100ms	The interval to pull data from The Graph
$${\color{red}\texttt{CollectDetailedValidatorSigningMetrics}}$$ CONTROLLER_COLLECT_DETAILED_VALIDATOR_SIGNING_METRICS type: bool default: true	If true, validators that DON'T have a human-friendly name remapping will be reported as their full validator ID in metrics. If false, validators that DON'T have a human-friendly name remapping will be reported as "0x0" in metrics. NOTE: No matter the value of this field, validators that DO have a human-friendly name remapping will be reported as their remapped name in metrics. If you must reduce metric cardinality by reporting ALL validators as "0x0", you shouldn't define any human-friendly name remappings.
$${\color{red}\texttt{ControllerReadinessProbePath}}$$ CONTROLLER_CONTROLLER_READINESS_PROBE_PATH type: string default: "/tmp/controller-ready"	The HTTP path to use for the controller readiness probe.
$${\color{red}\texttt{DispersalRequestSigner.Endpoint}}$$ CONTROLLER_DISPERSAL_REQUEST_SIGNER_ENDPOINT type: string default: ""	Endpoint is an optional custom AWS KMS endpoint URL. If empty, the standard AWS KMS endpoint is used. This is primarily useful for testing with LocalStack or other custom KMS implementations. Default is empty.
$${\color{red}\texttt{DisperserStoreChunksSigningDisabled}}$$ CONTROLLER_DISPERSER_STORE_CHUNKS_SIGNING_DISABLED type: bool default: false	If true, the disperser will not sign StoreChunks requests before sending them to validators.
$${\color{red}\texttt{EnablePerAccountBlobStatusMetrics}}$$ CONTROLLER_ENABLE_PER_ACCOUNT_BLOB_STATUS_METRICS type: bool default: true	If true, accounts that DON'T have a human-friendly name remapping will be reported as their full account ID in metrics. If false, accounts that DON'T have a human-friendly name remapping will be reported as "0x0" in metrics. NOTE: No matter the value of this field, accounts that DO have a human-friendly name remapping will be reported as their remapped name in metrics. If you must reduce metric cardinality by reporting ALL accounts as "0x0", you shouldn't define any human-friendly name remappings.
$${\color{red}\texttt{Encoder.EncodingRequestTimeout}}$$ CONTROLLER_ENCODER_ENCODING_REQUEST_TIMEOUT type: time.Duration default: 5m0s	EncodingRequestTimeout is the maximum time to wait for a single encoding request to complete. Must be positive.
$${\color{red}\texttt{Encoder.MaxNumBlobsPerIteration}}$$ CONTROLLER_ENCODER_MAX_NUM_BLOBS_PER_ITERATION type: int32 default: 128	MaxNumBlobsPerIteration is the maximum number of blobs to pull and encode in each iteration. Must be at least 1.
$${\color{red}\texttt{Encoder.NumConcurrentRequests}}$$ CONTROLLER_ENCODER_NUM_CONCURRENT_REQUESTS type: int default: 250	NumConcurrentRequests is the size of the worker pool for processing encoding requests concurrently. Must be at least 1.
$${\color{red}\texttt{Encoder.NumEncodingRetries}}$$ CONTROLLER_ENCODER_NUM_ENCODING_RETRIES type: int default: 3	NumEncodingRetries is the number of times to retry encoding a blob after the initial attempt fails. A value of 0 means no retries (only the initial attempt). Must be non-negative.
$${\color{red}\texttt{Encoder.NumRelayAssignment}}$$ CONTROLLER_ENCODER_NUM_RELAY_ASSIGNMENT type: uint16 default: 1	NumRelayAssignment is the number of relays to assign to each blob. Must be at least 1 and cannot exceed the length of AvailableRelays.
$${\color{red}\texttt{Encoder.PerAccountMetrics}}$$ CONTROLLER_ENCODER_PER_ACCOUNT_METRICS type: bool default: true	If true, accounts that DON'T have a human-friendly name remapping will be reported as their full account ID in metrics. If false, accounts that DON'T have a human-friendly name remapping will be reported as "0x0" in metrics. NOTE: No matter the value of this field, accounts that DO have a human-friendly name remapping will be reported as their remapped name in metrics. If you must reduce metric cardinality by reporting ALL accounts as "0x0", you shouldn't define any human-friendly name remappings.
$${\color{red}\texttt{Encoder.PullInterval}}$$ CONTROLLER_ENCODER_PULL_INTERVAL type: time.Duration default: 2s	PullInterval is how frequently the EncodingManager polls for new blobs to encode. Must be positive.
$${\color{red}\texttt{Encoder.StateRefreshInterval}}$$ CONTROLLER_ENCODER_STATE_REFRESH_INTERVAL type: time.Duration default: 1h0m0s	StateRefreshInterval is how frequently the manager refreshes blob version parameters from the chain. Must be positive.
$${\color{red}\texttt{Encoder.StoreTimeout}}$$ CONTROLLER_ENCODER_STORE_TIMEOUT type: time.Duration default: 15s	StoreTimeout is the maximum time to wait for blob metadata store operations. Must be positive.
$${\color{red}\texttt{EthClient.NumConfirmations}}$$ CONTROLLER_ETH_CLIENT_NUM_CONFIRMATIONS type: int default: 0	Number of block confirmations to wait for.
$${\color{red}\texttt{EthClient.NumRetries}}$$ CONTROLLER_ETH_CLIENT_NUM_RETRIES type: int default: 2	Max number of retries for each RPC call after failure.
$${\color{red}\texttt{EthClient.PrivateKeyString}}$$ CONTROLLER_ETH_CLIENT_PRIVATE_KEY_STRING type: string default: ""	Ethereum private key in hex string format.
$${\color{red}\texttt{EthClient.RetryDelay}}$$ CONTROLLER_ETH_CLIENT_RETRY_DELAY type: time.Duration default: 0s	Time duration for linear retry delay increment.
$${\color{red}\texttt{FinalizationBlockDelay}}$$ CONTROLLER_FINALIZATION_BLOCK_DELAY type: uint64 default: 75	FinalizationBlockDelay is the number of blocks to wait before using operator state. This provides a hedge against chain reorganizations.
$${\color{red}\texttt{HeartbeatMonitor.FilePath}}$$ CONTROLLER_HEARTBEAT_MONITOR_FILE_PATH type: string default: "/tmp/controller-health"	FilePath is the path to the file where heartbeat status will be written. Required.
$${\color{red}\texttt{HeartbeatMonitor.MaxStallDuration}}$$ CONTROLLER_HEARTBEAT_MONITOR_MAX_STALL_DURATION type: time.Duration default: 4m0s	MaxStallDuration is the maximum time allowed between heartbeats before a component is considered stalled. Required.
$${\color{red}\texttt{Indexer.PullInterval}}$$ CONTROLLER_INDEXER_PULL_INTERVAL type: time.Duration default: 1s	The frequency to pull data from The Graph.
$${\color{red}\texttt{Log.AddSource}}$$ CONTROLLER_LOG_ADD_SOURCE type: bool default: true	Enable source code location
$${\color{red}\texttt{Log.Format}}$$ CONTROLLER_LOG_FORMAT type: config.LogFormat default: json	Format of the log output. Valid options are "json" and "text".
$${\color{red}\texttt{Log.Level}}$$ CONTROLLER_LOG_LEVEL type: config.LogLevel default: debug	Minimum level to log. Valid options are "debug", "info", "warn", and "error".
$${\color{red}\texttt{Log.NoColor}}$$ CONTROLLER_LOG_NO_COLOR type: bool default: false	Disable color, only supported with text handler (i.e. no color in json).
$${\color{red}\texttt{Log.TimeFormat}}$$ CONTROLLER_LOG_TIME_FORMAT type: string default: ""	Time format, only supported with text handler
$${\color{red}\texttt{MaxBatchSize}}$$ CONTROLLER_MAX_BATCH_SIZE type: int32 default: 32	MaxBatchSize is the maximum number of blobs to include in a single batch for dispersal. Must be at least 1.
$${\color{red}\texttt{MaxDispersalAge}}$$ CONTROLLER_MAX_DISPERSAL_AGE type: time.Duration default: 45s	MaxDispersalAge is the maximum age a dispersal request can be before it is discarded. Dispersals older than this duration are marked as Failed and not processed. Age is determined by the BlobHeader.PaymentMetadata.Timestamp field, which is set by the client at dispersal request creation time (in nanoseconds since Unix epoch).
$${\color{red}\texttt{MaxDispersalFutureAge}}$$ CONTROLLER_MAX_DISPERSAL_FUTURE_AGE type: time.Duration default: 45s	The maximum a blob dispersal's self-reported timestamp can be ahead of the local wall clock time. This is a preventative measure needed to prevent an attacker from sending far future timestamps that result in data being tracked for a long time.
$${\color{red}\texttt{MetricsPort}}$$ CONTROLLER_METRICS_PORT type: int default: 9101	The port on which to expose prometheus metrics.
$${\color{red}\texttt{NodeClientCacheSize}}$$ CONTROLLER_NODE_CLIENT_CACHE_SIZE type: int default: 400	NodeClientCacheSize is the maximum number of node clients to cache for reuse. Must be at least 1.
$${\color{red}\texttt{NumConcurrentRequests}}$$ CONTROLLER_NUM_CONCURRENT_REQUESTS type: int default: 600	NumConcurrentRequests is the size of the worker pool for processing dispersal requests concurrently. Must be at least 1.
$${\color{red}\texttt{Payment.OnDemand.MaxLedgers}}$$ CONTROLLER_PAYMENT_ON_DEMAND_MAX_LEDGERS type: int default: 1024	The maximum number of OnDemandLedger entries to be kept in the LRU cache
$${\color{red}\texttt{Payment.OnDemand.UpdateInterval}}$$ CONTROLLER_PAYMENT_ON_DEMAND_UPDATE_INTERVAL type: time.Duration default: 30s	Interval for checking for payment updates
$${\color{red}\texttt{Payment.PerAccountMetrics}}$$ CONTROLLER_PAYMENT_PER_ACCOUNT_METRICS type: bool default: true	If true, enable a metric per user account for payment validation and authorization. Resulting metric may potentially have high cardinality.
$${\color{red}\texttt{Payment.Reservation.BucketCapacityPeriod}}$$ CONTROLLER_PAYMENT_RESERVATION_BUCKET_CAPACITY_PERIOD type: time.Duration default: 1m30s	Duration used to calculate bucket capacity when creating new reservation ledgers
$${\color{red}\texttt{Payment.Reservation.MaxLedgers}}$$ CONTROLLER_PAYMENT_RESERVATION_MAX_LEDGERS type: int default: 1024	The maximum number of ReservationLedger entries to be kept in the LRU cache. This may be automatically increased at runtime if premature ledger evictions are detected by the underlying cache.
$${\color{red}\texttt{Payment.Reservation.OverfillBehavior}}$$ CONTROLLER_PAYMENT_RESERVATION_OVERFILL_BEHAVIOR type: ratelimit.OverfillBehavior default: overfillOncePermitted	How to handle requests that would overfill the bucket
$${\color{red}\texttt{Payment.Reservation.UpdateInterval}}$$ CONTROLLER_PAYMENT_RESERVATION_UPDATE_INTERVAL type: time.Duration default: 30s	Interval for checking for payment updates
$${\color{red}\texttt{PullInterval}}$$ CONTROLLER_PULL_INTERVAL type: time.Duration default: 1s	PullInterval is how frequently the Dispatcher polls for new encoded blobs to batch and dispatch. Must be positive.
$${\color{red}\texttt{Server.MaxGRPCMessageSize}}$$ CONTROLLER_SERVER_MAX_GRPC_MESSAGE_SIZE type: int default: 1048576	Maximum size of a gRPC message that the server will accept (in bytes)
$${\color{red}\texttt{Server.MaxIdleConnectionAge}}$$ CONTROLLER_SERVER_MAX_IDLE_CONNECTION_AGE type: time.Duration default: 5m0s	Maximum time a connection can be idle before it is closed.
$${\color{red}\texttt{Server.RequestMaxFutureAge}}$$ CONTROLLER_SERVER_REQUEST_MAX_FUTURE_AGE type: time.Duration default: 3m0s	Maximum age of a request in the future that the server will accept. Requests with timestamps too far in the future will be rejected.
$${\color{red}\texttt{Server.RequestMaxPastAge}}$$ CONTROLLER_SERVER_REQUEST_MAX_PAST_AGE type: time.Duration default: 5m0s	Maximum age of a request in the past that the server will accept. Requests older than this will be rejected to prevent replay attacks.
$${\color{red}\texttt{SignatureTickInterval}}$$ CONTROLLER_SIGNATURE_TICK_INTERVAL type: time.Duration default: 50ms	SignatureTickInterval is how frequently attestations are updated in the blob metadata store as signature gathering progresses. Must be positive.
$${\color{red}\texttt{SignificantSigningThresholdFraction}}$$ CONTROLLER_SIGNIFICANT_SIGNING_THRESHOLD_FRACTION type: float64 default: 0.55	SignificantSigningThresholdFraction is a configurable "important" signing threshold fraction. Used to track signing metrics and understand system performance. If the value is 0, special handling for this threshold is disabled. Must be between 0.0 and 1.0.
$${\color{red}\texttt{SigningRateBucketSpan}}$$ CONTROLLER_SIGNING_RATE_BUCKET_SPAN type: time.Duration default: 10m0s	The duration of each signing rate bucket. Smaller buckets yield more granular data, at the cost of memory and storage overhead.
$${\color{red}\texttt{SigningRateFlushPeriod}}$$ CONTROLLER_SIGNING_RATE_FLUSH_PERIOD type: time.Duration default: 1m0s	The period at which signing rate data is flushed to persistent storage.
$${\color{red}\texttt{SigningRateRetentionPeriod}}$$ CONTROLLER_SIGNING_RATE_RETENTION_PERIOD type: time.Duration default: 336h0m0s	The amount of time to retain signing rate data.
$${\color{red}\texttt{UseGraph}}$$ CONTROLLER_USE_GRAPH type: bool default: true	Whether or not to use subgraph.
$${\color{red}\texttt{UserAccountRemappingFilePath}}$$ CONTROLLER_USER_ACCOUNT_REMAPPING_FILE_PATH type: string default: ""	The file path to a yaml file that maps user accounts (i.e. the parties submitting blobs) to human-friendly names, which are used for metrics.
$${\color{red}\texttt{ValidatorIdRemappingFilePath}}$$ CONTROLLER_VALIDATOR_ID_REMAPPING_FILE_PATH type: string default: ""	The file path to a yaml file that maps validator IDs to human-friendly names, which are used for metrics.