Crate sov_modules_api

sov-modules-api

The sov-modules-api crate provides essential traits for the Module System. Here are the key traits defined by the crate:

1. The Module trait: Defines how to initialize and change the state of a module. This is the main trait that module developers need to implement. The author of a module must specify:

   • Configuration upon rollup deployment: This includes the genesis() method and the Config type, which determine how the module is set up initially. Note that the initialization for logic for modules is identical to the Genesis trait (described below). We blanket implement Genesis for all Modules, but keep it as a separate trait since some other structs need to implement it as well.

   • Interaction with user messages: The module must define the call method and the CallMessage type, which handle user messages. These messages typically result in changes to the module’s state.

2. The ModuleInfo trait: Provides additional information related to a module. This trait is automatically derived.

3. The Spec trait: It defines all the types that modules are generic over. This separation allows the module logic to be independent of concerns such as the specific storage system or concrete signature schemes used for signing rollup transactions. Currently acceptable hashes for Spec should fit into 32 bytes.

4. The Context trait implements the Spec and introduces additional methods accessible within modules. Currently, it includes the sender() method, which returns the address of the transaction sender. This trait will be further extended with other useful methods, such as batch_hash(), and more. This crate defines also the default implementation for the Context trait.

5. The Genesis trait: Defines how the rollup is initialized during deployment phase.

6. The DispatchCall trait: Defines how messages are forwarded to the appropriate module and how the call message is executed. The implementation of this trait can be generated automatically using a macro.

Re-exports

• pub use sov_rollup_interface::digest;

Modules

• capabilities
  The rollup capabilities module defines “capabilities” that rollup must provide if they wish to use the standard app template. If you don’t want to provide these capabilities, you can bypass the Sovereign module-system completely and write a state transition function from scratch. See here for docs
• default_context
• default_signature
• hooks
• macros
  Procedural macros to assist with creating new modules.
• optimistic
• transaction

Structs

• Address
• AddressBech32
• CallResponse
  Response type for the Module::call method.
• Event
  A key-value pair representing a change to the rollup state
• Prefix
  A unique identifier for each state variable in a module.
• StateTransition
  The public output of a SNARK proof in Sovereign, this struct makes a claim that the state of the rollup has transitioned from initial_state_root to final_state_root if and only if the condition validity_condition is satisfied.

Enums

• Error
  General error type in the Module System.
• NonInstantiable
  A type that can’t be instantiated.
• SigVerificationError

Traits

• BasicAddress
  A marker trait for general addresses.
• BlobReaderTrait
  This trait wraps “blob transaction” from a data availability layer allowing partial consumption of the blob data by the rollup.
• Context
  A context contains information which is passed to modules during transaction execution. Currently, context includes the sender of the transaction as recovered from its signature.
• DaSpec
  A specification for the types used by a DA layer.
• DispatchCall
  A trait that needs to be implemented for any call message.
• EncodeCall
  A trait that specifies how a runtime should encode the data for each module
• Genesis
  Methods from this trait should be called only once during the rollup deployment.
• Module
  All the methods have a default implementation that can’t be invoked (because they take NonInstantiable parameter). This allows developers to override only some of the methods in their implementation and safely ignore the others.
• ModuleCallJsonSchema
  A Module that has a well-defined and known JSON Schema for its Module::CallMessage.
• ModuleInfo
  Every module has to implement this trait.
• PublicKey
  PublicKey used in the Module System.
• RollupAddress
  An address used inside rollup
• Signature
  Signature used in the Module System.
• SlotData
  SlotData is the subset of a DA layer block which is stored in the rollup’s database. At the very least, the rollup needs access to the hashes and headers of all DA layer blocks, but rollups may choose to partial (or full) block data as well.
• Spec
  The Spec trait configures certain key primitives to be used by a by a particular instance of a rollup. Spec is almost always implemented on a Context object; since all Modules are generic over a Context, rollup developers can easily optimize their code for different environments by simply swapping out the Context (and by extension, the Spec).
• ValidityCondition
  This trait is implemented on the struct/enum which expresses the validity condition
• ValidityConditionChecker
  This trait expresses that a type can check a validity condition.
• Zkvm
  A Zk proof system capable of proving and verifying arbitrary Rust code Must support recursive proofs.

Functions

• sort_values_by_modules_dependencies
  Accepts Vec<> of tuples (&ModuleInfo, &TValue), and returns Vec<&TValue> sorted by mapped module dependencies

Derive Macros

• DispatchCall
  Derives the DispatchCall trait for the underlying type.
• Genesis
  Derives the Genesis trait for the underlying runtime struct.
• MessageCodec
  Adds encoding functionality to the underlying type.
• ModuleCallJsonSchema
  Derives the ModuleCallJsonSchema trait for the underlying type.
• ModuleInfo
  Derives the ModuleInfo trait for the underlying struct.