Packet Structure and Provable Commitment Specification

interface Packet {
    // identifier for the destination-chain client existing on source chain
    sourceClientId: bytes,
    // identifier for the source-chain client existing on destination chain
    destClientId: bytes,
    // the sequence uniquely identifies this packet
    // in the stream of packets from source to dest chain
    sequence: uint64,
    // the timeout is the timestamp in seconds on the destination chain
    // at which point the packet is no longer valid.
    // It cannot be received on the destination chain and can
    // be timed out on the source chain
    timeout: uint64,
    // the data includes the messages that are intended
    // to be sent to application(s) on the destination chain
    // from application(s) on the source chain
    // IBC core handlers will route the payload to the desired
    // application using the port identifiers but the rest of the
    // payload will be processed by the application
    data: [Payload]
}

interface Payload {
    // sourcePort identifies the sending application on the source chain
    sourcePort: bytes,
    // destPort identifies the receiving application on the dest chain
    destPort: bytes,
    // version identifies the version that sending application
    // expects destination chain to use in processing the message
    // if dest chain does not support the version, the payload must
    // be rejected with an error acknowledgement
    version: string,
    // encoding allows the sending application to specify which
    // encoding was used to encode the app data
    // the receiving applicaton will decode the appData into
    // the strucure expected given the version provided
    // if the encoding is not supported, receiving application
    // must be rejected with an error acknowledgement.
    // the encoding string MUST be in MIME format
    encoding: string,
    // appData is the opaque content sent from the source application
    // to the dest application. It will be decoded and interpreted
    // as specified by the version and encoding fields
    appData: bytes,
}

func packetCommitmentPath(packet: Packet): bytes {
    return packet.sourceClientId + byte(0x01) + bigEndian(packet.sequence)
}

// commitPayload hashes all the fields of the packet data to create a standard size
// preimage before committing it in the packet.
func commitPayload(payload: Payload): bytes {
    buffer = sha256.Hash(payload.sourcePort)
    buffer = append(sha256.Hash(payload.destPort))
    buffer = append(sha256.Hash(payload.version))
    buffer = append(sha256.Hash(payload.encoding))
    buffer = append(sha256.Hash(payload.appData))
    return sha256.Hash(buffer)
}

// commitV2Packet commits to all fields in the packet
// by hashing each individual field and then hashing these fields together
// Note: SourceClient and the sequence are omitted since they will be included in the key
// Every other field of the packet is committed to in the packet which will be stored in the
// packet commitment value
// The final preimage will be prepended by the byte 0x02 before hashing in order to clearly define the protocol version
// and allow for future upgradability
func commitV2Packet(packet: Packet) {
    timeoutBytes = LittleEndian(packet.timeout)
    var appBytes: bytes
    for p in packet.payload {
        appBytes = append(appBytes, commitPayload(p))
    }
    buffer = sha256.Hash(packet.destClient)
    buffer = append(buffer, sha256.hash(timeoutBytes))
    buffer = append(buffer, sha256.hash(appBytes))
    buffer = append([]byte{0x02}, buffer)
    return sha256.Hash(buffer)
}

interface Acknowledgement {
    // Each app in the payload will have an acknowledgment in this list in the same order
    // that they were received in the payload
    // If an app does not need to send an acknowledgement, there must be a SENTINEL_ACKNOWLEDGEMENT
    // in its place
    // The app acknowledgement must be encoded in the same manner specified in the payload it received
    // and must be created and processed in the manner expected by the version specified in the payload.
    appAcknowledgement: [bytes]
}

func acknowledgementPath(packet: Packet) {
    return packet.destClientId + byte(0x02) + bigEndian(packet.Sequence)
}

// commitV2Acknowledgement hashes each app acknowledgment and hashes them together
// the final preimage will be prepended with the byte 0x02 before hashing in order to clearly define the protocol version
// and allow for future upgradability
func commitV2Acknowledgment(ack: Acknowledgement) {
    var buffer: bytes
    for appAck in ack.appAcknowledgement {
        buffer = append(buffer, sha256.Hash(appAck))
    }
    buffer = append([]byte{0x02}, buffer)
    return sha256.Hash(buffer)
}

func receiptPath(packet: Packet) {
    return packet.destClientId + byte(0x03) + bigEndian(packet.Sequence)
}