From 4499cd829c0519cc81766163d2d9b0607a2ee1c1 Mon Sep 17 00:00:00 2001 From: DimitrisJim Date: Tue, 9 Jul 2024 15:06:06 +0300 Subject: [PATCH] docs: restructure function docs to mention both cases separately. (#6781) --- modules/apps/transfer/keeper/relay.go | 33 ++++++++++++++++++--------- 1 file changed, 22 insertions(+), 11 deletions(-) diff --git a/modules/apps/transfer/keeper/relay.go b/modules/apps/transfer/keeper/relay.go index b14acc95fc3..d954bca42a8 100644 --- a/modules/apps/transfer/keeper/relay.go +++ b/modules/apps/transfer/keeper/relay.go @@ -154,11 +154,15 @@ func (k Keeper) sendTransfer( return sequence, nil } -// OnRecvPacket processes a cross chain fungible token transfer. If the -// sender chain is the source of minted tokens then vouchers will be minted +// OnRecvPacket processes a cross chain fungible token transfer. +// +// If the sender chain is the source of minted tokens then vouchers will be minted // and sent to the receiving address. Otherwise if the sender chain is sending // back tokens this chain originally transferred to it, the tokens are // unescrowed and sent to the receiving address. +// +// In the case of packet forwarding, the packet is sent on the next hop as specified +// in the packet's ForwardingPacketData. func (k Keeper) OnRecvPacket(ctx sdk.Context, packet channeltypes.Packet, data types.FungibleTokenPacketDataV2) error { // validate packet data upon receiving if err := data.ValidateBasic(); err != nil { @@ -265,12 +269,15 @@ func (k Keeper) OnRecvPacket(ctx sdk.Context, packet channeltypes.Packet, data t return nil } -// OnAcknowledgementPacket either reverts the state changes executed in receive -// and send packet if the chain acted as a middle hop on a multihop transfer; or -// responds to the success or failure of a packet acknowledgement written on the -// final receiving chain, if it acted as the original sender chain. If the -// acknowledgement was a success then nothing occurs. If the acknowledgement failed, -// then the sender is refunded their tokens using the refundPacketToken function. +// OnAcknowledgementPacket responds to the success or failure of a packet acknowledgment +// written on the receiving chain. +// +// If no forwarding occurs and the acknowledgement was a success then nothing occurs. Otherwise, +// if the acknowledgement failed, then the sender is refunded their tokens. +// +// If forwarding is used and the acknowledgement was a success, a successful acknowledgement is written +// for the forwarded packet. Otherwise, if the acknowledgement failed, after refunding the sender, the +// tokens of the forwarded packet that were received are in turn either refunded or burned. func (k Keeper) OnAcknowledgementPacket(ctx sdk.Context, packet channeltypes.Packet, data types.FungibleTokenPacketDataV2, ack channeltypes.Acknowledgement) error { forwardedPacket, isForwarded := k.getForwardedPacket(ctx, packet.SourcePort, packet.SourceChannel, packet.Sequence) @@ -308,9 +315,13 @@ func (k Keeper) OnAcknowledgementPacket(ctx sdk.Context, packet channeltypes.Pac } } -// OnTimeoutPacket either reverts the state changes executed in receive and send -// packet if the chain acted as a middle hop on a multihop transfer; or refunds -// the sender if the original packet sent was never received and has been timed out. +// OnTimeoutPacket processes a transfer packet timeout. +// +// If no forwarding occurs, it refunds the tokens to the sender. +// +// If forwarding is used and the chain acted as a middle hop on a multihop transfer, after refunding +// the tokens to the sender, the tokens of the forwarded packet that were received are in turn +// either refunded or burned. func (k Keeper) OnTimeoutPacket(ctx sdk.Context, packet channeltypes.Packet, data types.FungibleTokenPacketDataV2) error { if err := k.refundPacketTokens(ctx, packet, data); err != nil { return err