Trait exonum_rust_runtime::Service

pub trait Service: ServiceDispatcher + Debug + 'static {
    fn initialize(
        &self, 
        _context: ExecutionContext, 
        _params: Vec<u8>
    ) -> Result<(), ExecutionError> { ... }
    fn resume(
        &self, 
        _context: ExecutionContext, 
        _params: Vec<u8>
    ) -> Result<(), ExecutionError> { ... }
    fn before_transactions(
        &self, 
        _context: ExecutionContext
    ) -> Result<(), ExecutionError> { ... }
    fn after_transactions(
        &self, 
        _context: ExecutionContext
    ) -> Result<(), ExecutionError> { ... }
    fn after_commit(&self, _context: AfterCommitContext) { ... }
    fn wire_api(&self, _builder: &mut ServiceApiBuilder) { ... }
}

Describes an Exonum service instance.

Service determines how a service instance responds to certain requests and events from the runtime.

Implementation Requirements

Any changes of the storage state in the methods that can perform such changes (i.e., methods receiving ExecutionContext) must be the same for all nodes in the blockchain network. In other words, the service should only use data available in the provided context to perform such changes.

Provided methods

fn initialize(
    &self,
    _context: ExecutionContext,
    _params: Vec<u8>
) -> Result<(), ExecutionError>

Initializes a new service instance with the given parameters. This method is called once after creating a new service instance.

The default implementation does nothing and returns Ok(()).

The parameters passed to the method are not saved by the framework automatically, hence the user must do it manually, if needed.

fn resume(
    &self,
    _context: ExecutionContext,
    _params: Vec<u8>
) -> Result<(), ExecutionError>

Resumes a previously stopped service instance with given parameters. This method is called once after restarting a service instance.

The default implementation does nothing and returns Ok(()).

The parameters passed to the method are not saved by the framework automatically, hence the user must do it manually, if needed.

Migration workflow guarantees that the data layout is supported by the resumed service version.

fn before_transactions(
    &self,
    _context: ExecutionContext
) -> Result<(), ExecutionError>

Performs storage operations on behalf of the service before processing any transaction in the block.

The default implementation does nothing and returns Ok(()).

Services should not rely on a particular ordering of Service::before_transactions invocations among services.

fn after_transactions(
    &self,
    _context: ExecutionContext
) -> Result<(), ExecutionError>

Performs storage operations on behalf of the service after processing all transactions in the block.

The default implementation does nothing and returns Ok(()).

Note that if service was added in the genesis block, it will be activated immediately and thus after_transactions will be invoked for such a service after the genesis block creation. If you aren't interested in the processing of for the genesis block, you can use ExecutionContext::in_genesis_block method and exit early if true is returned.

Invocation of the height() method of the core blockchain schema will panic if invoked within after_transactions of the genesis block. If you are going to process the genesis block and need to know current height, use the next_height() method to infer the current blockchain height.

Services should not rely on a particular ordering of Service::after_transactions invocations among services.

fn after_commit(&self, _context: AfterCommitContext)

Handles block commit event.

This handler is a callback which is invoked by the blockchain after each block commit. For example, a service can broadcast one or more transactions if a specific condition has occurred.

The default implementation does nothing.

Try not to perform long operations in this handler since it is executed on the consensus thread.

fn wire_api(&self, _builder: &mut ServiceApiBuilder)

Attaches the request handlers of the service API to the Exonum API schema.

The default implementation does nothing (i.e., does not provide any API for the service).

The request handlers are mounted on the /api/services/{instance_name} path at the listen address of every full node in the blockchain network.

Loading content...

Implementors

Loading content...