query_interface.md

Query interface

Communication in ISMP is facilitated by offchain components, like relayers and self relaying wallets.
For these components to work, they need to be able to interact with the onchain components of the protocol.
For this purpose we define an interface that should be provided by state machines to allow querying ISMP data. Query results are formatted as JSON

/// A query for a request or a response
pub struct Query {
    /// The source of the request
    pub source_chain: StateMachine,
    /// the request destination
    pub dest_chain: StateMachine,
    /// The request nonce
    pub nonce: u64,
}

pub struct Proof {
    /// Scale encoded proof
    pub proof: Vec<u8>,
    /// Height at which proof was recovered
    pub height: u32,
}

pub trait QueryInterface {
    /// Query full request data from the ismp pallet
    fn query_requests(&self, query: Vec<Query>) -> Result<Vec<Request>>;

    /// Query full response data from the ismp pallet
    fn query_responses(&self, query: Vec<Query>) -> Result<Vec<Response>>;

    /// Query membership proof for some requests
    fn query_request_proof(&self, height: u32, query: Vec<Query>) -> Result<Proof>;

    /// Query membership proof for some responses
    fn query_response_proof(&self, height: u32, query: Vec<Query>) -> Result<Proof>;

    /// Query membership or non-membership state proof for some keys
    fn query_state_proof(&self, height: u32, keys: Vec<Vec<u8>>) -> Result<Proof>;

    /// Query scale encoded consensus state
    fn query_consensus_state(
        &self,
        height: Option<u32>,
        client_id: ConsensusClientId,
    ) -> Result<Vec<u8>>;

    /// Query timestamp of when this client was last updated in seconds
    fn query_consensus_update_time(&self, client_id: ConsensusClientId) -> Result<u64>;

    /// Query the latest height for a state machine
    fn query_state_machine_latest_height(&self, id: StateMachineId) -> Result<u64>;

    /// Query ISMP Events that were deposited in a series of blocks
    fn query_events(
        &self,
        block_numbers: Vec<u32>,
    ) -> Result<HashMap<u32, Vec<Event>>>;

    /// Query get requests that have no response receipt that have a specified retrieval height <=  `height`.
    fn pending_get_requests(&self, height: u64) -> Result<Vec<Get>>;
}