CelerPay On-Chain Contracts¶

Simplex channel state¶

We define a simplex state using protobuf as below, with proto3 field option used for Solidity native types to support smart contracts running on EVM.

// the simplex channel state from one peer to another
// two simplex channels constitute a full-duplex channel
message SimplexPaymentChannel {
    // unique channel ID per duplex channel
    bytes channel_id = 1 [(soltype) = "bytes32"];
    // address of the peer who owns and updates the simplex state
    bytes peer_from = 2 [(soltype) = "address"];
    // simplex state sequence number
    uint64 seq_num = 3 [(soltype) = "uint"];
    // amount of token already transferred to peer, monotonically increasing
    TokenTransfer transfer_to_peer = 4;
    // list of pending conditional payment IDs
    PayIdList pending_pay_ids = 5;
    // the last resolve deadline for all pending pays
    uint64 last_pay_resolve_deadline = 6 [(soltype) = "uint"];
    // total locked amount of all pending pays
    bytes total_pending_amount = 7 [(soltype) = "uint256"];
}

This proto data representation is shared by the off-chain protocol and the on-chain smart contracts of all layer-1 blockchains. A simplex state is only valid if it is co-signed and has the highest sequence number. Given two valid simplex states and the on-chain states of a duplex channel, one can compute the peer balances at any time. For example, the available balance of peer A for its next payment is: A.available = A.deposit - A.withdraw + B.transfer - A.transfer - A.pending

List of pending pay IDs¶

Details of the payment-related fields in the simplex state proto will be explained later. One thing to emphasize here is how the summary of all pending conditional payments are stored in the simplex state (field 5). We do not use Merkle proof because maintaining the Merkle root for a highly dynamic dataset is computationally expensive; and it also greatly increases the number of on-chain transactions during the dispute process. Instead, the list of pending pay IDs is stored in the simplex state directly. Sending or clearing a conditional payment off-chain is simply adding or removing the payment ID from the list (field 5), and updating the transfer amount (field 4) if needed. On-chain contracts never need to store the pending pay IDs; they only need to scan the list from the input and compute the outcome in one transaction, as will be detailed in later sections. The proto message below shows the structure of the pending pay list used in the simplex state.

// linked list of payID list to record arbitrarily number of pending pays
// used in SimplexPaymentChannel field 5
message PayIdList {
    // list of pay IDs
    repeated bytes pay_ids = 1 [(soltype) = "bytes32"];
    // hash of the next PayIdList
    bytes next_list_hash = 2 [(soltype) = "bytes32"];
}

All layer-1 blockchains have a gas limit to restrict how big data a single transaction can process. To overcome this restriction, we use a linked list of lists data structure to support a potentially large number of pending pays. In practice, we expect a single list should be enough for most cases. For example, in Ethereum, we can put at least hundreds of pay IDs in the list within the simplex state to be processed in a single transaction.

Condition¶

Each payment can be associated with a list of Condition, and a resolving logic TransferFunction which takes the conditions as input.

// condition of a payment, used in ConditionalPay field 4
message Condition {
    // three types: hash_lock, deployed_contract, virtual_contract
    ConditionType condition_type = 1;
    // one of the following three fields:
    // 1. hash of the secret preimage
    bytes hash_lock = 2 [(soltype) = "bytes32"];
    // 2. onchain deployed contract
    bytes deployed_contract_address = 3 [(soltype) = "address"];
    // 3. offchain virtual contract
    bytes virtual_contract_address = 4 [(soltype) = "bytes32"];
    // arg to query condition status from the deployed or virtual contract
    bytes args_query_finalization = 5;
    // arg to query condition outcome from the deployed or virtual contract
    bytes args_query_outcome = 6;
}

Message above shows the proto representation of a condition. There are three condition types:

• Hash Lock Condition. This is used to secure a multi-hop payment. The payment source includes a hash h (field 2) of a secret preimage as a condition. The payment can only be resolved on-chain if the hash preimage v is revealed. Though hash lock could be also expressed through the contract conditions below, we separate it for protocol performance optimization.
• Deployed Contract Condition. The condition could be based on the state of an on-chain deployed contract (field 3), which is able to implement arbitrary application logic. Such a contract needs to expose isFinalized and getOutcome APIs for the CelerPay contracts to query the states of the condition through arguments given in fields 5 and 6. The outcomes can be derived from state channel application results, oracle contract outputs, on-chain NFT ledgers, ENS name ownerships, roll-up chain states, etc.
• Virtual Contract Condition. The condition can also stay off-chain as a virtual contract counterfactually instantiated by involved parties (e.g., payment source and destination). A virtual contract only needs to be deployed on-chain if someone wants to dispute, in which case CelerPay can find where to call the isFinalized and getOutcome APIs through a unique identifier (field 4) computed by the hash of the virtual contract code, initial states, and a nonce.

Note on decoupled architecture: getOutcome is a generic interface to get some data from the dependency contract that can be interpreted into arbitrary resolution results on the committed fund for the payment. While there are some common cases that we have implemented and optimized, this clean decoupling of application logic and fund allocation protocol allows the maximal level of flexibility.

Transfer function¶

Given the list of conditions, one can compute the payment amount according to the transfer_func field in the ConditionalPay message once all conditions have outcomes. Condition outcomes can be a boolean or numeric value. CelerPay supports flexible functionalities to resolve the payment amount based on condition outcomes. Below is the proto of the transfer function.

// payment result resolving function, takes pay.conditions as input
// used in ConditionalPay field 5
message TransferFunction {
    // amount resolving logic based on the condition outcome
    TransferFunctionType logic_type = 1;
    // maximum token transfer amount of this payment
    TokenTransfer max_transfer = 2;
}

enum TransferFunctionType {
    BOOLEAN_AND = 0;     // pay full amount if every condition is true
    BOOLEAN_OR = 1;      // pay full amount if any condition is true
    BOOLEAN_CIRCUIT = 2; // customized boolean circuit logic, not supported yet
    NUMERIC_ADD = 3;     // pay the sum of all condition outcomes
    NUMERIC_MAX = 4;     // pay the max of all condition outcomes
    NUMERIC_MIN = 5;     // pay the min of all condition outcomes
}

To summarize, ConditionalPay is a self-contained unit that carries all the information related to a conditional payment. We will elaborate how to send/receive a payment off-chain and how to resolve a payment on-chain in case of dispute in later sections.

Cooperative withdraw¶

When both peers are online and cooperative, the withdrawer can finish the operation within one quick transaction by calling the cooperativeWithdraw API and submitting the peer co-signed cooperative withdrawal message. Once the co-signed message is submitted, the CelerLedger contract will transfer the tokens from the channel’s wallet in the CelerWallet contract to either the account address or another channel as specified in the co-signed withdrawal message.

Unilateral withdraw¶

When the withdrawer is not able to find its peer to co-sign the above cooperative withdrawal message, it can initiate a unilateral withdraw by calling the intendWithdraw function, which takes the channel ID, withdrawal amount, and the optional recipient channel ID as inputs. Once the transaction is submitted, the challenge time window is opened for the other peer to call vetoWithdraw if it does not approve the withdrawal. After the challenge window closed, if the other peer did not veto, the withdrawer can call confirmWithdraw to finish the operation.

Resolve payment by conditions¶

One can call the resolvePaymentByConditions API of the PayResolver once all conditions of a payment are finalized on-chain. The API input consists of two pieces of information: 1) the full conditional payment data and 2) all hash preimages of the hash locks associated with the payment. Then the PayResolver will verify the hash preimages, query the condition outcomes, then compute and set the payment result in the PayRegistry, as depicted in the contracts architecture figure.

Whoever tries to resolve a payment by conditions needs to make sure the conditions are all finalized on-chain, otherwise the transaction will fail. Conditions on virtual contracts need to be first instantiated on-chain through the VirtContractResolver contract. These are considered as parts of the CelerApp instead of the CelerPay operations.

Only the payment source or destination may initiate the transaction to resolve a payment by the conditions. An intermediate relay node never calls this API for a payment. The later off-chain protocol section will explain the flow in detail.

Resolve payment by vouched result¶

The payment relay node never needs to care about the internal conditions, but only the amount they should safely receive from upstream and pay to the downstream. CelerPay provides a unique feature to let relay nodes quickly resolve a payment on-chain with their peers through the vouched result co-signed by the source and destination (field 2 and 3 of the ConditionalPay message).

As will be elaborated in the off-chain protocol section, every node along the payment route can use that as a proof to ask its upstream peer to clear the payment according to the vouched amount. Any node who has the co-signed vouched result can call the resolvePaymentByVouchedResult API to resolve this payment on-chain and set the result in the PayRegistry.

Dispute the payment result¶

All CelerNodes along a payment route share the result of the payment in the PayRegistry. Proper on-chain and off-chain mechanisms are required to guarantee the security of the relay nodes in case of colluding payment source and destination co-sign different vouched results or manipulate the condition outcomes maliciously. PayResolver writes a payment result to the PayRegistry according to the following rules:

• If the resolving result equals to the maximum amount of the transfer function (field 5 of the ConditionalPay message), the result is instantly finalized in the PayRegistry.
• Otherwise, a challenge time window (according to field 7 of the ConditionalPay message) is opened for others to resolve the same payment (with potentially different input messages). Once a result is written in the PayRegistry, it can only be updated to a larger amount before finalization, which is a joint design with the off-chain protocol. The payment result gets finalized after the challenge window closed or the resolve deadline passed, whichever comes earlier.

Cooperative settle¶

The CelerLedger contract exposes a cooperativeSettle API which the peer co-signed cooperative settle request information as input. Once the contract receives the co-signed request, it will close the channel and distribute the balances according to the requested amounts. Both off-chain simplex channel states including all the pending payments will be ignored when executing a cooperative settle transaction.

Unilateral settle¶

If cooperative settling is not possible, a peer can initiate a unilateral settling by calling the intendSettle API, which takes the co-signed off-chain simplex states as input. The CelerLedger contract will compute the settled balance distributions based on the simplex states and the results of pending payments queried from the PayRegistry.

A challenge time window is opened after the unilateral settle request, for the other peer to submit simplex channel states with higher sequence numbers if exist. After the challenge window is closed, one can call the confirmSettle API to finish the operation and close the channel.