# Penumbra ICA V2 Proposal Sketch

This document has a sketch of a proposed "ICA V2" created by the Penunba team, brainstorming during an offsite in Seattle. The "Penumbra" in the title just indicates the source; the proposal is intended to not be Penumbra-specific. For the purposes of this document, we use the term "PICA" rather than "ICA V2" to emphasize that this is just, like, our opinion, man, and is a starting point for discussion rather than a definitive view of what ICA V2 should be.

> The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

## Overall Design Goals

Achieved:

- [x] Provide a general-purpose ICA standard that makes minimal assumptions about the underlying state machine (i.e., does not require the Cosmos SDK);
- [x] Ensure that users can self-relay their own account packets;
- [x] Scale to potentially millions of accounts;

TODO:

- [ ] Allow funding an account on creation with an ICS20 transfer (how to interact with the ICS20 channel state?)
- [ ] Allow releasing value from the account to self-fund gas for relaying

## Definitions

- **Host Chain**: the chain where the account exists; receives IBC messages and updates account state
- **Controller Chain**: the chain that controls the _host chain_ account; which sends IBC messages to update _host chain_;
- **Account ID**: an identifier for a particular PICA account;

## Application Design

PICA should use a single unordered channel for all accounts. Like an application operating over UDP, we leave the message ordering as a problem for the application layer, and allow the network layer to send and receive packets in an arbitrary order.

Accounts within a channel are identified by an integer account number:

((port_id: string, host_channel_id: string), account_num: u64)

This identifier is encoded in string format as

# Format
{port_id}/{host_channel_id}/{account_num}
# Example
pica/channel-234/7654321

Host chains SHOULD accept the string encoding of a PICA account identifier as an address. Host chains MAY create alternate address encodings for PICA account identifiers. For example, the host chain could define an address to be the PICA account ID, a hash thereof, or something else.

There is no assumption that the PICA account on the host chain has a controller account. The mechanism the controller uses to delegate control of PICA accounts is intentionally out-of-scope.

## PICA Channel Messages

PICA defines two actions:

- `CreateAccount`, used for creating an account;
- `Transact`, used for performing actions with an account.

Messages are wrapped in a `PicaPacket` container, and acknowledgement data is wrapped in a `PicaPacketAck` container. This ensures forward extensibility, as new actions and acknowledgements can be added later without breaking message formats.

All messages are encoded into packets as binary protobuf data.

message PicaPacket {
    oneof msg {
        CreateAccount create_account = 2;
        Transact transact = 3;
    }
}

message PicaPacketAck {
    // The status of packet processing.
    //
    // - `0` represents success.
    // - `1` represents failure due to invalid packet encoding.
    // - `2` represents a mismatched `Transact` sequence number.
    // - All other status codes represent failure and are host-defined.
    uint64 status = 1;
    
    // Only present when `status = 0` (success)
    oneof msg {
        CreateAccountResponse create_account_response = 2;
        TransactResponse transact_response = 3;
    }
}

Because all received packets must be acknowledged, even if they are invalid, the `PicaPacketAck` has a separate `status` field with an error code. The status code `0` (which, as the Protobuf default value, will not be encoded) represents success. The status code `1` represents an invalid `PicaPacket` encoding, which was not further processed. The status code `2` represents a mismatched `Transact` sequence number (see below). These status codes are intentionally _not_ specified as a Protobuf enum, to steer client tooling away from assuming that a list of PICA-specific error codes are exhaustive.

In the success case, the `PicaPacketAck` can contain structured data about the response.

### `CreateAccount`

// Creates an account on the host chain.
message CreateAccount {
    // The account number of the account to create.
    uint64 account_num = 1;
}

// Data returned on successful processing of `CreateAccount`
message CreateAccountResponse { }

The `CreateAccount` message is used by the controller chain to create an account on the host chain. The account number is assigned by the controller chain, rather than the host chain, so that the controller chain can assign account numbers synchronously.

The controller chain SHOULD assign account numbers sequentially. The controller chain MUST initialize the account with a **controller sequence number**, initially set to `0`. This is a counter of `Transact` messages sent by the controller chain.

The host chain MUST accept account numbers out-of-order, so that users can self-relay only their own packets. The host chain MUST reject `CreateAccount` messages with duplicate account numbers.

On creation, the host chain MUST initialize the account with a **host sequence number**, initially set to `0`. This is a counter of `Transact` messages acked by the host chain.

The `CreateAccount` message could be extended with additional fields that impose capability restrictions or other data on the created account.

### `Transact`

// A bundle of messages to atomically perform on the host chain.
message Transact {
    uint64 account_num = 1;
    uint64 sequence = 2;
    
    repeated google.protobuf.Any msgs = 3;
}

// Data returned by the host chain to the controller on success.
message TransactResponse {
    uint64 account_num = 1;
    uint64 sequence = 2;
    
    repeated google.protobuf.Any data = 3;
}

The `Transact` message is used by the controller chain to perform actions on the host chain.

The controller chain MUST increment the controller sequence number by one before creating a `Transact` message and use the updated controller sequence number for the `sequence` field of the newly produced `Transact` message.

The host chain MUST reject a `Transact` message whose sequence number is not exactly one greater than the sequence number for the account prior to processing the message. The host chain MUST increment the account's host sequence number by one every time it processes a `Transact` message, regardless of success.

The `msgs` in the `Transact` message should be decoded by the host chain and executed in sequence. If any of them fail, execution of the entire sequence should fail without modifications to the chain state. Unknown `Any` types count as execution failures.

On success, the host chain writes a `TransactResponse` (inside a `PicaPacketAck`) as an acknowledgement. The host chain MUST replicate the `account_num` and `sequence` fields from the `Transact` message. The host chain MAY include additional data about the resulting account state in the `data` field.

## Controller and Host Sequence Numbers

Because PICA does not use an ordered channel, packet ordering must be handled at the application level. The sequence number design for the `Transact` messages is intended to ensure that:

1. `Transact` messages are not accepted out of order;
2. there is no protocol-level requirement to relay acks to the controller chain;
3. there is no need for relayers to have insight into the packet contents.

Rejecting `Transact` messages whose sequence number is not exactly one greater than the host sequence number ensures that they are not accepted out of order (1).

A client (whether on- or off-chain) can ensure that `Transact` messages will have the correct sequence number by only causing the creation of a subsequent `Transact` message after observing the prior message's arrival on the host chain. This satisfies (2), because if the client is off-chain, no on-chain ack is required. And as long as clients do so, property (3) is satisfied because all packets available to relayers would be accepted if they were relayed.

If a client causes multiple `Transact` messages for the same `account_num` to be produced by the controller chain without waiting for them to be relayed to the host chain, the messages could be relayed out-of-order, causing the `Transact` sequence numbers from the controller chain to desynchronize from the host chain sequence number. In this case, however, synchronization can be restored by relaying all packets for that account.

For example, consider the following scenario. A client creates a new account and then causes the controller chain to produce a `Transact` message `T1` with sequence number `1`. `T1` is relayed to the host chain, where it is accepted because `host_sequence = 0`. Then `host_sequence <- 1` because a `Transact` packet was processed. Then `T2`, `T3` with sequence numbers `2`, `3` are produced simultaneously but `T3` is relayed first. `T3` will be rejected, because `host_sequence = 1` but `T3.sequence = 3`. Because the host processed the packet (to reject it), `host_sequence <- 2`. Now the host and controller sequence numbers have desynchronized: the next `Transact` message would have `sequence = 4` but only `sequence = 3` would be accepted. However, "flushing" the account by relaying `T2` (even though it will be rejected) will re-synchronize the host and controller sequence numbers, allowing message passing to resume.

This design is a compromise between protocol simplicity and efficiency and client and relayer behavior. It enables unordered channel semantics and self-relaying, and allows a common case (clients wait for one action to be performed before creating a new action) to work without any changes to relayer behavior. In the event that a client allows the creation of conflicting packets that could then be sent out of order, it allows repairing the desynchronization just by relaying all of the conflicting packets. And it does all of this without requiring any changes to IBC channel semantics or to relayers.

## Closing Accounts

Closing accounts is not supported, though there is in principle nothing preventing it from being possible in the future. Since this would not remove existing state, there does not seem to be a clear benefit.

# Example Controller Implementations

## Penumbra

This design is compatible with a Penumbra controller implementation that creates many unlinkable ICAs on the host chain, each separately controlled by a bearer NFT recorded in the Penumbra shielded pool. Because this means that control over the ICA is just like any other asset, this mechanism also allows buying and selling ICAs on the Penumbra DEX, or sending the ICA itself over ICS-20 to any other Cosmos chain.

The [Penumbra Transaction Model](https://protocol.penumbra.zone/main/transactions.html) may be a helpful reference.

### PICA NFTs

A PICA NFT is bound to two pieces of data: a sequence number and a 32-byte nonce. This data is encoded into a denom string as follows:

pica_{seq}_{bech32m("n", nonce)}
# Example
pica_0_n1tyysmd023vzz2fylngasxasawt0dqux230mkjkgmljf0vqvdygqsguuycm
pica_1_n1tyysmd023vzz2fylngasxasawt0dqux230mkjkgmljf0vqvdygqsguuycm

### Transaction Actions

#### `ActionPicaCreateAccount`

This action triggers the Penumbra chain's PICA controller to send a `CreateAccount` message to the host chain.

message ActionPicaCreate {
    // The channel to the host chain to use.
    string channel = 1;
    // A random, 32-byte nonce.
    bytes nonce = 2;
}

##### Value Balance

The action's effect on the transaction's value balance is to consume the input amount and produce a PICA NFT that may control the account:

| Value Balance Consumed | Value Balance Produced |
|-|-|
| $-$ (input value) | $+$ (PICA NFT, seq 0, nonce `n`) |

Clients will presumably record the resulting PICA NFT in the shielded pool using an `Output` action.

#### `ActionPicaTransact`

This action triggers the Penumbra chain's PICA controller to send a `Transact` message to the host chain.

message ActionPicaTransact {
    // The channel to the host chain to use.
    string channel = 1;
    // The nonce to look up the account number.
    bytes nonce = 2;
    // The sequence number of the `Transact` message.
    uint64 sequence = 3;
    // The messages to relay to the host chain.
    repeated google.protobuf.Any = 4;
}

##### Value Balance

The action's effect on the transaction's value balance is to consume the PICA NFT for the current sequence number and produce one with the next sequence number:

| Value Balance Consumed | Value Balance Produced |
|-|-|
| $-$ (PICA NFT, seq `s`, nonce `n`) | $+$ (PICA NFT, seq `s+1`, nonce `n`) |

Clients will presumably need to fund the action with a `Spend` that releases the first PICA NFT from the shielded pool to be burned by the action and to record the second PICA NFT in the shielded pool using an `Output` action.

### Component Logic

#### Handling `ActionPicaCreateAccount`

The component implementation should maintain a lookup table of nonce values to account numbers. If the user-provided nonce has previously been used, the action is rejected. Otherwise, the component allocates the next account number for the channel to it and writes the `CreateAccount` message in a packet to the host chain.

The nonce mechanism bridges between the early binding required by Penumbra's shielded value balance mechanism (like Bitcoin, all transactions' action balances must sum to zero, statelessly), and the late binding required by the controller's role allocating account numbers. The action always produces a bearer NFT, and after execution that bearer NFT will correspond to a specific PICA account.

#### Handling `ActionPicaTransact`

The value balance mechanism should already be sufficient to ensure that no on-chain tracking of the controller sequence number is required, as it's encoded into the denoms of the bearer NFTs. However, for robustness, the controller should track and check consistency of this data, halting the chain if it is inconsistent.