Description

A new type of clearing smart contract is needed to perform the following actions:

• accept incoming withdrawal obligations and store them in a FIFO queue
• allow an authorized strategist to settle the oldest items in the queue

which should be enabled with the following execute message:

pub enum ExecuteMsg {
    /// validates and enqueues a new withdrawal obligation
    RegisterObligation(WithdrawalObligation),
    /// settles the oldest withdrawal obligation
    SettleNextObligation {},
}

Withdrawal obligation registration

Example definition may look as follows:

/// unsettled liability sitting in the clearing queue
WithdrawalObligation {
    recipient: String,       // where the payout is to be routed
    payout_coins: Vec<Coin>,  // what is owed to the recipient
    id: Uint256,               // some unique identifier for the request
}

Withdrawal obligations that arrive to this contract are assumed to be correct due to some
actions on other domains.

The contract should ensure that:

1. the withdrawal obligation being registered is coming from a valid source
2. the recipient address is valid

If both checks pass, the obligation is pushed to the queue.

Settlement account

The settlement account associated with this contract is a Valence Base account.

In Valence Protocol terms, settlement account will function as the input account from which
funds are to be routed to the final recipients.

Funding of the settlement account is outside the scope of this contract. This contract is
just the settlement engine.

Liquidity-management flow, which will also be operated by the strategist, will be responsible
for continuously monitoring the settlement account balance and the obligation queue in order
to keep the settlement account topped up with sufficient/desired liquidity.

Obligation settlement

Obligations are settled by the approved strategist.

Settlement happens by transferring funds from the settlement account to the recipient specified
in each WithdrawalObligation being processed.

This contract will delegate BankSend instructions to the settlement account in order to
carry out the final payouts.

Settlement should happen as follows:

1. pop the head of the obligation queue and error out if it's empty
2. validate that the associated settlement (input) account has sufficient funds for the payout
3. delegate the payout transfer message to the settlement account

Future work

In the future, this obligation registration and settlement can be batched. Keeping it simple for now.