Ocular Transaction API Design Proposal

[cbrit]

Ocular Transaction API Design Proposal

Overview

This proposal outlines an API for transaction construction, signing, and broadcasting that is more flexible than having a method per message type, more easily extended for custom modules, and, in my opinion, is very readable.

Goals

• Extensibility for non-core Cosmos SDK module msgs
• Readability; specifically, it should be easy to tell what each argument value maps to in a particular transaction Msg, and what module a particular Msg maps to.
• Tx construction decoupled from the chain client
• Support for building transactions that contain multiple messages
• Seamless support for Authz

Non-goals

• Exhaustive support of popular modules
• Macros for implementing the model for non-SDK modules

Design

Each core Cosmos SDK module’s set of transaction Msgs will map to an enum representation, where each variant corresponds to a particular Msg. Each variant will take in an anonymous struct whose fields correspond to the Msg parameters. This approach makes it very easy to tell exactly what msg is being constructed and what parameter each argument represents. An example of what the Bank module implementation might look like (without MultiSend):

pub enum Bank<'m> {
    Send {
        from: &'m str,
        to: &'m str,
        amount: u64,
        denom: &'m str,
    },
}

Each of these enums will implement a ModuleMsg trait responsible for providing a common way to serialize a msg to a prost::Any. There will also be a trait IntoTx which will blanket implement an into_tx() method on all ModuleMsg which converts them into an UnsignedTx.

pub trait ModuleMsg<'m, Err> {
    fn to_any(self) -> Result<prost_types::Any, Err>;
}

// blanket implemented on all ModuleMsg
pub trait IntoTx<Err>
{
    fn into_tx(self) -> Result<UnsignedTx, Err>;
}

This trait makes this tx model easily extensible because all that needs to be done to use it with a non-SDK module is create an enum with variants that represent each msg, and implement ModuleMsg for it. The implementation is pretty straight forward and will look very similar for most msgs.

The UnsignedTx type acts like a builder for the final transaction. It contains a vec of msgs and a method for adding new ones, sensible defaults for all metadata/tx configuration, and setters for each. Finally, it has a method .sign() used to build the final Tx object and sign it with the provided account. Signing converts the UnsignedTx to a SignedTx, a wrapper for the raw transaction bytes that provides a broadcast method.

pub struct UnsignedTx {
    msgs: Vec<Any>,
    fee: Coin,
    fee_payer: Option<AccountId>,
    fee_granter: Option<AccountId>,
    gas_limit: u64,
    timeout_height: u32,
    memo: String,
}

pub struct SignedTx {
    inner: Raw,
}

Example Usage

// given account `sender` and address `recipient`, send ATOM
let client = ChainClient::create(COSMOSHUB).await?;
let response = Bank::Send {
        from: &sender.address("cosmos")?,
        to: &recipient,
        amount: 1000000,
        denom: "uatom"
    }
    .into_tx()?
    .gas_limit(250000)
    .timeout_height(100000000)
    .sign(&mut client, &sender)
    .await?
    .broadcast(&mut client)
    .await?;

Future work

The outlined traits and their implementations are simple enough that it may be possible to create a macro impl_msgs!() which generates an enum and the ModuleMsg implementation automatically given a proto or generated proto definitions.

Tony has suggested part or all of this model may be a good fit for the cosmrs crate.

[AlianBenabdallah]

This design achieves all the objectives.

I wonder if it would be possible to avoid storing a Vec<Any>. As long as the item inside this Vec implements ModuleMsg, it looks possible to turn an UnsignedTx to a SignedTx. Any call of to_any() would be hidden within .signed().

[cbrit]

@AlianBenabdallah Thanks for the feedback! I think I tried something like this and can't remember exactly what stopped me. iirc it got weird because of wrapping the trait object with a Box and then having to account for the lifetime parameter... I'll go back and see.

In any cause, I think .into_tx() would abstract any noticeable use of to_any() unless I'm missing something? The idea was to keep the msgs filed of the UnsignedTx private so the user wouldn't have to use it, and then if you want to add a msg to an already existing tx, there can be a tx.add_msg() method that can internally use to_any().

[AlianBenabdallah]

Indeed, using Box with a trait leads to account for the lifetime parameter. I am still learning Rust but I wonder if this would do the trick :

pub struct UnsignedTx<'a>{
    msgs: Vec<Box<dyn ModuleMsg + 'a>>,
}
impl<'a> UnsignedTx<'a> {
    fn add_msg<T : ModuleMsg + 'a> (self: &'_ mut Self, message: T)
    {
        self.msgs.push(Box::new(message)); // I doubt that it will work  
    }
}

Keeping msgs private will indeed avoid any problem, even with Any, if the only use case is to pack messages into transactions. However, it might be useful to have other methods to access the messages and manipulate them.

In most cases, the current API format would be enough but some cases might lead to manipulate the messages before signing the transaction. For example example, before signing, you could check that you don't spend more than N tokens in a single transaction or merge messages.

With the current API, it is still possible to do all these checks before building the transactions but there might be some cases where accessing the messages could be helpful.

What do you think about it @cbrit ?