Overview The Internet Computer protocol defines public interfaces for various replica components in rs/interfaces/. These traits establish contracts between components, enabling modular development and testing while reducing unnecessary dependencies.
Consensus Interfaces Defined in rs/interfaces/src/consensus.rs
PayloadBuilder Responsible for creating and validating payloads included in consensus blocks.
Trait Definition: pub trait PayloadBuilder : Send + Sync { fn get_payload ( & self , height : Height , past_payloads : & [( Height , Time , Payload )], context : & ValidationContext , subnet_records : & SubnetRecords , ) -> BatchPayload ; fn validate_payload ( & self , height : Height , proposal_context : & ProposalContext , payload : & Payload , past_payloads : & [( Height , Time , Payload )], ) -> ValidationResult < PayloadValidationError >; }
Methods: Produces a payload that is valid given past payloads and the current context. The block height for which to create the payload
past_payloads
&[(Height, Time, Payload)]
Payloads from blocks above the certified height, in descending order
Validation context including certified state and registry version
Current subnet configuration and records
Validates whether a proposed payload is valid given the context and past payloads. The block height of the payload being validated
Context of the block proposal
past_payloads
&[(Height, Time, Payload)]
Previously finalized payloads for validation context
PayloadValidationError Represents validation errors that can occur during payload validation.
Rust Definition: pub type PayloadValidationError = ValidationError < InvalidPayloadReason , PayloadValidationFailure >; pub enum InvalidPayloadReason { InvalidXNetPayload ( InvalidXNetPayload ), InvalidIngressPayload ( InvalidIngressPayloadReason ), InvalidSelfValidatingPayload ( InvalidSelfValidatingPayloadReason ), InvalidCanisterHttpPayload ( InvalidCanisterHttpPayloadReason ), InvalidQueryStatsPayload ( InvalidQueryStatsPayloadReason ), InvalidVetKdPayload ( InvalidVetKdPayloadReason ), PayloadTooBig { expected : NumBytes , received : NumBytes , }, }
PayloadWithSizeEstimate Contains a payload together with an estimate of its wire size (not necessarily the same as in-memory size).
Rust Definition: pub struct PayloadWithSizeEstimate < T > { pub payload : T , pub wire_size_estimate : NumBytes , }
Registry Interfaces Defined in rs/interfaces/registry/src/lib.rs
RegistryClient Provides methods to query the local state of the registry. All methods return immediately with no side effects on the critical path.
Trait Definition: pub trait RegistryClient : Send + Sync { fn get_versioned_value ( & self , key : & str , version : RegistryVersion , ) -> RegistryClientVersionedResult < Vec < u8 >>; fn get_key_family ( & self , key_prefix : & str , version : RegistryVersion , ) -> Result < Vec < String >, RegistryClientError >; fn get_value ( & self , key : & str , version : RegistryVersion ) -> RegistryClientResult < Vec < u8 >>; fn get_latest_version ( & self ) -> RegistryVersion ; fn get_version_timestamp ( & self , registry_version : RegistryVersion ) -> Option < Time >; }
Key Methods: Retrieves a registry value at a specific version, returning both the value and metadata. For any key k: get_value(k, get_latest_version()).is_ok() - reported versions are fully available
The registry at version 0 has a known empty state
Two calls with the same arguments always return equal values (if both succeed)
Returns all keys starting with the given prefix that are present at the specified version. List of matching keys (no duplicates, unordered)
Returns the latest registry version known to this replica. Eventually consistent.
Returns the time when a specific version became available locally.
RegistryVersionedRecord RegistryVersionedRecord<T>
A versioned key-value pair returned from the registry.
Rust Definition: pub struct RegistryVersionedRecord < T > { pub key : String , pub version : RegistryVersion , pub value : Option < T >, }
Fields: The version at which this record was added/updated
The value at this version (None means the key was deleted)
RegistryDataProvider Data source backing the RegistryClient. In production, queries the registry canister on the NNS. For testing, can read from local files.
Trait Definition: pub trait RegistryDataProvider : Send + Sync { fn get_updates_since ( & self , version : RegistryVersion , ) -> Result < Vec < RegistryRecord >, RegistryDataProviderError >; }
Method: Returns registry updates between the given version and some later version. All returned records have version > input version
Returns all updates for versions in range (version..max_version], where max_version is the maximum version in results
Type Aliases Represents a versioned key-value pair as stored in the registry canister.
pub type RegistryRecord = RegistryVersionedRecord < Vec < u8 >>;
Result type for registry value queries.
pub type RegistryClientResult < T > = Result < Option < T >, RegistryClientError >;
RegistryClientVersionedResult<T>
Result type for versioned registry queries.
pub type RegistryClientVersionedResult < T > = Result < RegistryVersionedRecord < T >, RegistryClientError >;
Constants The empty registry at version 0.
pub const ZERO_REGISTRY_VERSION : RegistryVersion = RegistryVersion :: new ( 0 );
How often the registry client polls the local store for updates.
pub const POLLING_PERIOD : Duration = Duration :: from_secs ( 5 );
Component Interfaces The rs/interfaces/src/lib.rs module exports interfaces for all replica components:
Available Interface Modules
batch_payload Batch payload construction and validation
canister_http Canister HTTP outcalls interface
certification State certification interfaces
consensus Consensus protocol interfaces
consensus_pool Consensus artifact pool management
crypto Cryptographic operations
dkg Distributed key generation
execution_environment Canister execution environment
idkg Interactive DKG protocols
ingress_manager Ingress message management
ingress_pool Ingress message pool
messaging Cross-subnet messaging (XNet)
p2p Peer-to-peer communication
query_stats Query statistics tracking
self_validating_payload Self-validating payload types
time_source Time source abstraction
validation General validation utilities
vetkd Verifiable threshold key derivation
Design Philosophy Associated Types Several traits use associated types to avoid direct dependencies on complex types like ReplicatedState. This design:
Creates a cleaner dependency graph
Speeds up incremental compilation
Enables better separation of concerns
Facilitates testing with mock implementations
Trait Bounds All interfaces require Send + Sync to ensure:
Thread-safe sharing across replica components
Safe concurrent access to shared state
Compatibility with async execution contexts
Example Usage Implementing RegistryClient use ic_interfaces_registry :: { RegistryClient , RegistryClientResult }; use ic_types :: RegistryVersion ; struct MyRegistryClient { // implementation fields } impl RegistryClient for MyRegistryClient { fn get_versioned_value ( & self , key : & str , version : RegistryVersion , ) -> RegistryClientVersionedResult < Vec < u8 >> { // Query local registry cache // ... } fn get_latest_version ( & self ) -> RegistryVersion { // Return current version // ... } // ... implement other methods }
Using PayloadBuilder use ic_interfaces :: consensus :: PayloadBuilder ; fn create_block_payload < P : PayloadBuilder >( builder : & P , height : Height , context : & ValidationContext , ) -> BatchPayload { builder . get_payload ( height , & [], // past payloads context , & subnet_records , ) }
See Also 