ADR-20: Cross-Chain Transfers

type MsgRecvPacket struct {
    Packet  exported.Packet
    Proof   []byte
    ProofHeight clienttypes.Height
    Signer  string
}

type Packet struct {
	Sequence uint64
	SourcePort string
	SourceChannel string
	DestinationPort string
	DestinationChannel string
	Data []byte               // <----- FungibleTokenPacketData
	TimeoutHeight types.Height
	TimeoutTimestamp uint64
}

// Data field in Packet
type FungibleTokenPacketData struct {
	Denom string
	Amount string
	Sender string
	Receiver string
	Memo string // <----- IBCInboundMemo
}

// Memo field in FungibleTokenPacketData
type IBCInboundMemo struct {
	SourceChain     string  `json:"source-chain"`       // Source chain, for example: 'osmosis' <- if transfer is sent from Osmosis
	DestChain       string  `json:"dest-chain"`         // Destination chain, for example: 'dogecoin' <- if transfer is sent to Dogecoin
	DestAddress     string  `json:"dest-address"`       // Destination address, for example: 'D6Z26L69gdk9qYmMkVtL9bXGKp8Be7ZfL8' <- Dogecoin address
	RefundOnFailure bool    `json:"refund-on-failure"`  // Flag to indicate if the transfer should be refunded
}

type MsgTransfer struct {
    SourcePort string
    SourceChannel string
    Token sdk.Coin
    Sender string
    Receiver string
    TimeoutHeight clienttypes.Height
    TimeoutTimestamp uint64
    Memo string // <----- IBCOutboundMemo
}

// Memo field in MsgTransfer
type IBCOutboundMemo struct {
    OutboundTxHash string `json:"outbound_tx_hash"` // TxHash of outbound transfer on Int3face Chain
    IsRefund       bool   `json:"is_refund"`        // Flag to indicate if the transfer is a refund
	IsRetry        bool   `json:"is_retry"`         // Flag to indicate if the transfer is a retry
}

// When the inbound IBC packet is RECEIVED.
func (im IBCMiddleware) OnRecvPacket(
    ctx sdk.Context,
    packet channeltypes.Packet,
    relayer sdk.AccAddress,
) ibcexported.Acknowledgement {
    // Validate the packet data
    if err := im.validatePacketData(ctx, data); err != nil {
        return ibc.NewEmitErrorAcknowledgement(err)
    }
    
    // Process outbound transfer
    if err := im.bridgeKeeper.OutboundTransfer(ctx, data); err != nil {
        return nil, nil, err
    }

    // Pass the packet to the next middleware
    return im.next.OnRecvPacket(ctx, packet, data)
}

// When the outbound IBC packet is ACKNOWLEDGED.
func (im IBCMiddleware) OnAcknowledgementPacket(
    ctx sdk.Context,
    packet channeltypes.Packet,
    ack ibcexported.Acknowledgement,
    relayer sdk.AccAddress,
) error {
    // Parse packet memo
    memo, err := im.parsePacketMemo(packet)
    if err != nil {
        return err
    }
    
    if memo.IsRefund {
        // Refund the outbound transfer
        if err := im.bridgeKeeper.SetOutboundTransferRefunded(ctx, memo.OutboundTxHash); err != nil {
            return err
        }
    }
    
    // Finalize the outbound transfer
    if err := im.bridgeKeeper.SetOutboundTransferFinalized(ctx, memo.OutboundTxHash); err != nil {
        return err
    }

    // Pass the packet to the next middleware
    return im.next.OnAcknowledgementPacket(ctx, packet, ack, relayer)
}

Transfer(tokens_unlocked) -> IBCMiddleware(outbound_validated_and_sent)

message MsgInboundTransfer {
  // ExternalId is a unique ID of the transfer coming from outside.
  // Serves the purpose of uniquely identifying the transfer in another chain
  // (e.g., this might be the BTC tx hash)
  string external_id = 1;
  // ExternalHeight is the height at which the transfer occurred in the external
  // chain
  uint64 external_height = 2;
  // Sender is a sender's address
  string sender = 3;
  // DestAddr is a destination Int3face address
  string dest_addr = 4;
  // AssetID is the ID of the asset being transferred
  AssetID asset_id = 5;
  // Amount of coins to transfer
  string amount = 6;
  // DestChainId is a destination chain of the transfer. If this id is not
  // Int3face chain, we need to perform forwarding of the tokens to the
  // destination chain.
  string dest_chain_id = 7;
  // SrcChainId is a source chain of the transfer origin.
  string src_chain_id = 8;
}

message MsgInboundTransferRetry {
  // ExternalId is a unique ID of the transfer coming from outside.
  // Serves the purpose of uniquely identifying the transfer in another chain
  // (e.g., this might be the BTC tx hash)
  string external_id = 1;
  // ExternalHeight is the height at which the transfer occurred in the external chain.
  uint64 external_height = 2;
}

message MsgInboundTransferPushBack {
  // ExternalId is a unique ID of the transfer coming from outside.
  required string external_id = 1;
  // ExternalHeight is the height at which the transfer occurred in the external chain.
  required uint64 external_height = 2;
}

message MsgInboundTransferRefunded {
  // ExternalId is a unique ID of the transfer coming from outside.
  required string external_id = 1;
  // ExternalHeight is the height at which the transfer occurred in the external chain.
  required uint64 external_height = 2;
}

message MsgInboundTransferRefundFailed {
  // ExternalId is a unique ID of the transfer coming from outside.
  required string external_id = 1;
  // ExternalHeight is the height at which the transfer occurred in the external chain.
  required uint64 external_height = 2;
  // Reason is a reason of the failure.
  required string reason = 3;
}

message MsgOutboundTransfer {
  // Sender is a sender's Int3face address
  string sender = 1;
  // DestAddr is a destination address
  string dest_addr = 2;
  // AssetID is the ID of the asset being transferred
  AssetID asset_id = 3;
  // Amount of coins to transfer
  string amount = 4;
  // DestChainId is a destination chain of the transfer.
  string dest_chain_id = 5;
}

message MsgOutboundTransferRetry {
  // TxHash is a hash of Outbound Transfer on the Int3face chain.
  string tx_hash = 1;
}

message MsgOutboundTransferFinalized {
  // TxHash is a hash of Outbound Transfer on the Int3face chain.
  string tx_hash = 1;
  // BroadcastedTxHash is a hash of the broadcasted transaction on the destination chain.
  string broadcasted_tx_hash = 2;
}

message MsgOutboundTransferFailed {
  // TxHash is a hash of Outbound Transfer on the Int3face chain.
  string tx_hash = 1;
  // Reason is a reason of the failure.
  string reason = 2;
}

int3faced q bridge params

// Asset is a representation of the asset.
message Asset {
  // ID is the asset's primary key
  AssetID id = 1;
  // Status is a current status of the asset
  AssetStatus status = 2;
  // Exponent represents the power of 10 used for coin representation
  uint64 exponent = 3;
  // ExternalConfirmations is a number of the confirmations on the external
  // chain needed to consider the transfer confirmed
  uint64 external_confirmations = 4;
  // Minimal amount of tokens for transfer
  string min_transfer_amount = 5;
  // ExecutionPeriod defines how long transfer for the given asset required to
  // be in the execution until it can be retried.
  uint64 execution_period = 6;
  // GracePeriod defines how long after the execution period transfer for the
  // given asset can be retried.
  uint64 grace_period = 7;
  // BridgingRoutes defines the list of the chain identifiers where the asset can be transferred.
  repeated BridgingRoute bridging_routes = 8;
}

message AssetID {
  // SourceChain is a source chain name
  string source_chain = 1;
  // Denom is the SourceChain denom
  string denom = 2;
}

enum AssetStatus {
  ASSET_STATUS_UNSPECIFIED = 0;
  ASSET_STATUS_OK = 1;
  ASSET_STATUS_BLOCKED_INBOUND = 2;
  ASSET_STATUS_BLOCKED_OUTBOUND = 3;
  ASSET_STATUS_BLOCKED_BOTH = 4;
}

message BridgingRoute {
  // SourceChain is a source chain name
  string source_chain = 1;
  // DestinationChain is a destination chain name
  string destination_chain = 2;
  // RefundEnabled indicates whether the asset can be refunded back to the source chain by this route
  bool refund_enabled = 3;
}

int3faced q bridge inbound-transfer [external-id/external-height]

int3faced q bridge inbound-transfer [source-channel/dest-channel/sequence]

int3faced q bridge inbound-transfers --limit 100

message InboundTransfer {
  // Status is a current status of the inbound transfer
  required InboundTransferStatus status = 1;
  // ExternalId is a unique ID of the transfer coming from outside.
  // Serves the purpose of uniquely identifying the transfer in another chain
  // (e.g., this might be the BTC tx hash).
  // Or in case of IBC transfer, it's a {source_channel}-{destination_channel}-{sequence}
  // Example: channel-8836-channel-0-234
  required string external_id = 2;
  // ExternalHeight is the height at which the transfer occurred in the external chain.
  // In case of IBC transfer, it will be zero, because IBC doesn't have the height in transfer data.
  required uint64 external_height = 3;
  // AssetID is the ID of the asset being transferred
  required AssetID asset_id = 4;
  // Amount of coins to transfer
  required string amount = 5;
  // SrcAddr is a source address to refund the tokens in case of the transfer failure.
  required string src_addr = 6;
  // SrcChainId is a source chain of the transfer origin.
  required string src_chain_id = 7;
  // DestAddr is a destination address
  required string dest_addr = 8;
  // DestChainId is a destination chain of the transfer. If this id is not
  // Int3face chain, we need to perform outbound transfer of the tokens to the destination chain.
  required string dest_chain_id = 9;
  // RefundOnFailure indicates whether the transfer can be refunded in case of failure.
  // Tokens will be refunded on the SrcChainId to the SrcAddr.
  required bool refund_on_failure = 10;
  // Voters is a list of validators signed this transfer
  required InboundTransferVotes votes = 11;
  // FinalizedTxHash is a hash of the final int3face transaction which finalized the transfer and minted the tokens.
  required string finalized_tx_hash = 12;
  // ReceivedVia is a channel that was used to receive the transfer.
  required TransferProtocol received_via = 13;
  // CreationTimestamp is a timestamp when the inbound transfer was created
  required uint64 creation_timestamp = 14;
  // LastUpdateAt is a timestamp when the inbound transfer was updated
  required uint64 last_update_timestamp = 15;
}

message AssetID {
  // SourceChain is a source chain name
  required string source_chain = 1;
  // Denom is the SourceChain denom
  required string denom = 2;
}

message InboundTransferVotes {
  // Finalized is a list of validators signed this transfer on finalization
  repeated VoteOnFinalization finalized = 1;
  // PushBack is a list of validators signed this transfer on push back (in case of invalid memo and impossibility to process inbound)
  repeated VoteOnPushBack push_back = 2;
  // Refunded is a list of validators signed this transfer on refunding
  repeated VoteOnRefund refunded = 3;
  // RefundFailed is a list of validators signed this transfer on refunding failure
  repeated VoteOnFailure refund_failed = 4;
}

message VoteOnFinalization {
  // Voter is a validator signed this transfer on finalization
  required string voter = 1;
}

message VoteOnPushBack {
  // Voter is a validator signed this transfer on push back
  required string voter = 1;
  // Reason is a reason of the push back
  required string reason = 2;
}

message VoteOnRefund {
  // Voter is a validator signed this transfer on refunding
  required string voter = 1;
  // BroadcastedTxHash is a hash of the broadcasted transaction on the source chain
  required string broadcasted_tx_hash = 2;
}

message VoteOnFailure {
  // Voter is a validator signed this transfer on refunding
  required string voter = 1;
  // Reason is a reason of the refunding
  required string reason = 2;
}

enum TransferProtocol {
  IBC = 0;
  BITFROST = 1;
}

enum InboundTransferStatus {
  PROCESSING = 0;
  FINALIZED = 1;
  REFUNDING = 2;
  REFUNDED = 3;
  REFUND_FAILED = 4;
}

int3faced q bridge outbound-transfer [int3face-tx-hash]

int3faced q bridge outbound-transfers --limit 100

message OutboundTransfer {
  // Status is a current status of the outbound transfer
  required OutboundTransferStatus status = 1;
  // SentVia is a protocol used for the transfer to sent
  required TransferProtocol sent_via = 2;
  // SrcChainId is a source chain of the transfer origin.
  required string src_chain_id = 3;
  // DestChainId is a destination chain of the transfer
  required string dest_chain_id = 4;
  // DestAddr is a destination address on the destination chain
  required string dest_addr = 5;
  // AssetId is the asset is being transferred
  required AssetID asset_id = 6;
  // Amount of coins to transfer
  required string amount = 7;
  // CreationTimestamp is a timestamp when the outbound transfer was created
  required uint64 creation_timestamp = 8;
  // ResolutionTimestamp is a timestamp when the outbound transfer was updated last time
  required uint64 last_update_timestamp = 9;
  // OutboundTransferVotes is a list of different votes collected during the outbound transfer lifecycle
  required OutboundTransferVotes votes = 10;
  // RefundOnFailure indicates whether the transfer can be refunded in case of failure
  required bool refund_on_failure = 11;
  // InboundContext is a context of the inbound transfer that was used to create the outbound transfer
  optional InboundTransferContext inbound_context = 11;
}

message AssetID {
  // SourceChain is a source chain name
  required string source_chain = 1;
  // Denom is the SourceChain denom
  required string denom = 2;
}

message InboundTransferContext {
  // ExternalId is a unique ID of the transfer coming from outside.
  // Serves the purpose of uniquely identifying the transfer in another chain
  // (e.g., this might be the BTC tx hash).
  // Or in case of IBC transfer, it's a {source_channel}-{destination_channel}-{sequence}
  // Example: channel-8836-channel-0-234
  required string external_id = 1;
  // ExternalHeight is the height at which the transfer occurred in the external chain.
  // in case of IBC transfer, it will be zero, because IBC doesn't have the height in transfer data.
  optional uint64 external_height = 2;
}

message OutboundTransferVotes {
  // Finalized is a list of validators signed this transfer on finalization
  repeated VoteOnFinalization finalized = 1;
  // Failed is a list of validators signed this transfer on failure
  repeated VoteOnFailure failed = 2;
}

message VoteOnFinalization {
  // Voter is a validator signed this transfer on finalization
  required string voter = 1;
  // BroadcastedTxHash is a hash of the broadcasted transaction on the destination chain
  required string broadcasted_tx_hash = 2;
}

message VoteOnFailure {
  // Voter is a validator signed this transfer on refunding
  required string voter = 1;
  // Reason is a reason of the refunding
  required string reason = 2;
}

enum OutboundTransferStatus {
  PROCESSING = 0;
  FINALIZED = 1;
  FAILED = 2;
  REFUNDED = 3;
}

enum TransferProtocol {
  IBC = 0;
  BITFROST = 1;
}