Skip to main content
An application is the actor on one chain that wants to talk to another chain over IBC. They communicate by sending and receiving packets across an IBC connection. This page covers a packet’s fields, the payload inside it, what an application is, ports, and the callbacks applications can implement. A packet is like a piece of mail. The packet is the envelope with routing information, and the payload inside is the letter. The application that is the recipient of the packet opens it and decides what to do with the information.

​
The packet

A packet is one unit of information a relayer carries from one chain to another. It holds what an application wants to send, together with the routing information IBC needs to deliver it and verify it.
The first four fields are the routing information. The last one is the application’s content. This is similar to the same split TCP makes between a header and a payload.
  • sequence: the packet’s number on its source client. It comes from a counter that starts at 1 and increments by one with every send, so both chains can refer to the same packet.
  • sourceClient and destClient: the two ends of the route. sourceClient is the source chain’s light client of the destination; destClient is the destination chain’s client of the source.
  • timeoutTimestamp: the deadline in unix seconds, after which the packet can no longer be received. The timestamp represents the destination chain’s block time, and a relayer times it out on the source chain. On send the router requires it to be in the future and no more than one day out.
  • payloads: the application’s content.

​
The payload

A payload is an application’s message as raw bytes, plus information naming the application at each end and saying how to read those bytes.
  • sourcePort and destPort: the ports of the sending and the receiving application.
  • version: the version of the application protocol that value follows.
  • encoding: the format the value bytes are written in.
  • value: the message itself, opaque to IBC, the way a network carries a TCP payload without reading it.
IBC moves value but never interprets it. The application registered on destPort is what gives those bytes their meaning. An application also decides which versions and encodings it answers to.

​
Applications

Applications are the business logic that give meaning to packets. They are the logic at each end of an IBC connection that wants to communicate. An application owns the value field of the payload: what goes in, how it is encoded, and what happens at each step of the packet’s life. IBC core delivers packets but never interprets them, so the application is responsible for the meaning. Sending an IBC packet begins inside the application. An application runs its own logic, then hands the router a send message with its source client, a timeout, and its payload.

​
Sending a packet

An application does not build a full packet. It submits a smaller message to the router on the source chain and the router completes the rest.
The application is responsible for supplying the source client, the timeout, and the payload. When the application calls the router, IBC core derives destClient from the source client’s counterparty, assigns the next sequence, assembles the Packet, and commits it. The application owns its data and the route it wants; the router owns sequence numbering and the destination side of the route.

​
Ports and registration

An application is registered with the IBC router on its chain, under a port. Each port identifies one application, and ports are how the router knows which application a packet is for and how to route it. A port is either the application’s own address as a hex string or a readable name like GMP’s gmpport. The access manager decides who may register each kind. Once registered, the port identifier remains with that application permanently. Every payload names two ports:
  • destPort says which application the payload is for.
  • sourcePort says who sent it, and only the application registered there may send on it.

​
Application callbacks

Applications can register callbacks that the router executes at different stages of the packet lifecycle.
Each callback handles one moment in a packet’s life.
  • onRecvPacket runs on the destination chain when a packet arrives. The application decodes the payload, acts on it, and returns an acknowledgement. If it reverts with a reason, the router writes a universal error acknowledgement in its place and the packet still settles. If it reverts with no reason (like running out of gas), the whole receive fails and the packet stays undelivered.
  • onAcknowledgementPacket runs on the source chain once the destination’s acknowledgement is proven. The application reads the result and settles accordingly.
  • onTimeoutPacket runs on the source chain when a packet’s deadline passes without delivery. The application releases or reverses whatever it staged on send, or tells the sender so it can.
An acknowledgement is non-empty bytes the receiving application chooses, other than the one value reserved for errors. IBC proves them and carries them back to the sender without reading them. The sending application gets either those bytes or the one reserved error value the router writes when a receive fails. Across these callbacks, an application carries a clear set of responsibilities:
  • Sending: encode value and set the version and encoding.
  • On receipt: validate the version and encoding, decode value, act, and return an acknowledgement.
  • On the return leg: handle either the acknowledgement or the timeout of the packet.
The router handles routing, recording, and verification. The application handles meaning. For the order these callbacks fire in, and what the router does between them, see the packet lifecycle.