Struct ibc_relayer::foreign_client::ForeignClient

pub struct ForeignClient<DstChain: ChainHandle, SrcChain: ChainHandle> {
    pub id: ClientId,
    pub dst_chain: DstChain,
    pub src_chain: SrcChain,
}

Fields

id: ClientId

The identifier of this client. The host chain determines this id upon client creation, so we may be using the default value temporarily.

dst_chain: DstChain

A handle to the chain hosting this client, i.e., destination chain.

src_chain: SrcChain

A handle to the chain whose headers this client is verifying, aka the source chain.

Implementations

impl<DstChain: ChainHandle, SrcChain: ChainHandle> ForeignClient<DstChain, SrcChain>

pub fn new(
    dst_chain: DstChain,
    src_chain: SrcChain
) -> Result<ForeignClient<DstChain, SrcChain>, ForeignClientError>

Creates a new foreign client on dst_chain. Blocks until the client is created, or an error occurs. Post-condition: dst_chain hosts an IBC client for src_chain.

pub fn restore(
    id: ClientId,
    dst_chain: DstChain,
    src_chain: SrcChain
) -> ForeignClient<DstChain, SrcChain>

pub fn find(
    expected_target_chain: SrcChain,
    host_chain: DstChain,
    client_id: &ClientId
) -> Result<ForeignClient<DstChain, SrcChain>, ForeignClientError>

Queries host_chain to verify that a client with identifier client_id exists. If the client does not exist, returns an error. If the client exists, cross-checks that the identifier for the target chain of this client (i.e., the chain whose headers this client is verifying) is consistent with expected_target_chain, and if so, return a new ForeignClient representing this client.

pub fn upgrade(&self) -> Result<Vec<IbcEvent>, ForeignClientError>

pub fn dst_chain(&self) -> DstChain

Returns a handle to the chain hosting this client.

pub fn src_chain(&self) -> SrcChain

Returns a handle to the chain whose headers this client is sourcing (the source chain).

pub fn id(&self) -> &ClientId

pub fn build_create_client(
    &self,
    options: CreateOptions
) -> Result<MsgCreateAnyClient, ForeignClientError>

Lower-level interface for preparing a message to create a client.

pub fn build_create_client_and_send(
    &self,
    options: CreateOptions
) -> Result<IbcEvent, ForeignClientError>

Returns the identifier of the newly created client.

pub fn validated_client_state(
    &self
) -> Result<(AnyClientState, Option<Duration>), ForeignClientError>

pub fn is_expired_or_frozen(&self) -> bool

pub fn refresh(&mut self) -> Result<Option<Vec<IbcEvent>>, ForeignClientError>

pub fn build_update_client(
    &self,
    target_height: Height
) -> Result<Vec<Any>, ForeignClientError>

Wrapper for build_update_client_with_trusted.

pub fn build_update_client_with_trusted(
    &self,
    target_height: Height,
    trusted_height: Height
) -> Result<Vec<Any>, ForeignClientError>

Returns a vector with a message for updating the client to height target_height. If the client already stores a consensus state for this height, returns an empty vector.

pub fn build_latest_update_client_and_send(
    &self
) -> Result<Vec<IbcEvent>, ForeignClientError>

pub fn build_update_client_and_send(
    &self,
    height: Height,
    trusted_height: Height
) -> Result<Vec<IbcEvent>, ForeignClientError>

pub fn update(&self) -> Result<(), ForeignClientError>

Attempts to update a client using header from the latest height of its source chain.

pub fn update_client_event(
    &self,
    consensus_height: Height
) -> Result<Option<UpdateClient>, ForeignClientError>

Retrieves the client update event that was emitted when a consensus state at the specified height was created on chain. It is possible that the event cannot be retrieved if the information is not yet available on the full node. To handle this the query is retried a few times.

pub fn detect_misbehaviour(
    &self,
    update: Option<UpdateClient>
) -> Result<Option<MisbehaviourEvidence>, ForeignClientError>

Checks for evidence of misbehaviour. The check starts with and update_event emitted by chain B (dst_chain) for a client update with a header from chain A (src_chain). The algorithm goes backwards through the headers until it gets to the first misbehaviour.

The following cases are covered: 1 - fork: Assumes at least one consensus state before the fork point exists. Let existing consensus states on chain B be: [Sn,.., Sf, Sf-1, S0] with Sf-1 being the most recent state before fork. Chain A is queried for a header Hf' at Sf.height and if it is different than the Hf in the event for the client update (the one that has generated Sf on chain), then the two headers are included in the evidence and submitted. Note that in this case the headers are different but have the same height.

2 - BFT time violation for unavailable header (a.k.a. Future Lunatic Attack or FLA): Some header with a height that is higher than the latest height on A has been accepted and a consensus state was created on B. Note that this implies that the timestamp of this header must be within the clock_drift of the client. Assume the client on B has been updated with h2(not present on/ produced by chain A) and it has a timestamp of t2 that is at most clock_drift in the future. Then the latest header from A is fetched, let it be h1, with a timestamp of t1. If t1 >= t2 then evidence of misbehavior is submitted to A.

3 - BFT time violation for existing headers (TODO): Ensure that consensus state times are monotonically increasing with height.

Other notes:

• the algorithm builds misbehavior at each consensus height, starting with the highest height assuming the previous one is trusted. It submits the first constructed evidence (the one with the highest height)
• a lot of the logic here is derived from the behavior of the only implemented client (ics07-tendermint) and might not be general enough.

pub fn detect_misbehaviour_and_submit_evidence(
    &self,
    update_event: Option<UpdateClient>
) -> MisbehaviourResults

pub fn map_chain<DstChain2: ChainHandle, SrcChain2: ChainHandle>(
    self,
    map_dst: impl Fn(DstChain) -> DstChain2,
    map_src: impl Fn(SrcChain) -> SrcChain2
) -> ForeignClient<DstChain2, SrcChain2>

Trait Implementations

impl<DstChain: Clone + ChainHandle, SrcChain: Clone + ChainHandle> Clone for ForeignClient<DstChain, SrcChain>

fn clone(&self) -> ForeignClient<DstChain, SrcChain>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<DstChain: Debug + ChainHandle, SrcChain: Debug + ChainHandle> Debug for ForeignClient<DstChain, SrcChain>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<DstChain: ChainHandle, SrcChain: ChainHandle> Display for ForeignClient<DstChain, SrcChain>

Used in Output messages. Provides a concise description of a ForeignClient, using the format: {CHAIN-ID} -> {CHAIN-ID}:{CLIENT} where the first chain identifier is for the source chain, and the second chain identifier is the destination (which hosts the client) chain.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.