smartaccount

SMART-ACCOUNT

a smart account solution for CosmWasm-enabled chains.

In our context, smart account is a contract account associated with a public key, so it can be considered a programmable EOA. The difference is that unlike an EOA account where Address and PubKey must be the same, the PubKey of a smart account can be any key that the account owner set for it.

Our new account will have SmartAccount type instead of BaseAccount or other existing types.

Activation Account

Like EOA, users can create a local smart account and decide when to actually use it. This achived by using cosmwasm Instantiate2 method which will generate an account with predictable address.

• Instantiate2 method params
  • sender: actor that signerd the messages.
  • admin: optional address that can execute migrations.
  • code_id: reference to the stored WASM code.
  • label: optional metadata to be stored with a contract instance.
  • msg: json encoded message to be passed to the contract on instantiation.
  • funds: coins that are transferred to the contract on instantiation.
  • salt: an arbitrary value provided by the sender. Size can be 1 to 64.
  • fix_msg: include the msg value into the hash for the predictable address. Default is false.

Query generate-account

Allows users to generate smart account addresses locally based on optional configuration

type QueryGenerateAccount struct{
    // reference to the stored WASM code, must be in whitelist
    code_id    uint64

    // an arbitrary value provided by the sender. Size can be 1 to 64.
    salt       []byte

    // json encoded message to be passed to the contract on instantiation
    init_msg   []byte

    // public key of this account, must be cosmos supported schemas
    public_key Any
}

Internally a address is built by Instantiate2 containing:

(len(checksum) | checksum | len(sender_address) | sender_address | len(salt) | salt| len(initMsg) | initMsg)

When create a new EOA, users can generate their private key locally and claim their account without sending any transactions. In our smart account case, using public_key as sender_address, a smart account can be claimed to be owned by the user who has configured the parameters to generate the account address.

Message activate-account

Allows users to activate their smart account. This message will take an account with type BaseAccount and convert it to SmartAccount type with preconfigured public key. Account address must be generated by QueryGenerateAccount query

type MessageActivateAccount struct {
    // AccountAddress is the actor who signs the message
    account_address string

    // reference to the stored WASM code, must be in whitelist
    code_id         uint64

    // an arbitrary value provided by the sender. Size can be 1 to 64.
    salt            []byte

    // json encoded message to be passed to the contract on instantiation
    init_msg        []byte

    // public key of this account, must be cosmos supported schemas
    public_key      Any
}

This message is signed with the user's private key and the signer is a pre-generated account. The module will calculate the expected address based on the input parameters then compare with the signer's address, so all configuration needs to match that used for the QueryGenerateAccount query.

To illustrate this in a graph:

             tx
              ↓
  ┌───── Antehandler ─────┐
  │   ┌───────────────┐   │
  │   │  decorator 0  │   │
  │   └───────────────┘   │
  │   ┌───────────────┐   │ Set temporary PubKey      ┌───────────────┐
  │   │  SA SetPubKey │---│-------------------------->|  auth module  |
  │   └───────────────┘   │                           └───────────────┘
  |      ...........      |
  │   ┌───────────────┐   │
  │   │SigVerification│   │
  │   └───────────────┘   │
  |      ...........      |
  │   ┌───────────────┐   │ Remove temporary Pubkey   ┌───────────────┐
  │   │  SA decorator │---│-------------------------->|  auth module  |
  │   └───────────────┘   │                           └───────────────┘
  │   ┌───────────────┐   │
  │   │  decorator 2  │   │
  │   └───────────────┘   │
  └───────────────────────┘
              ↓
      ┌────────────────┐
      │  msg activate  │ 
      └────────────────┘
              ↓
  ┌───────  module ───────┐
  │   ┌───────────────┐   │   instantiate contract   ┌───────────────┐
  │   │   SA module   │---│------------------------->|  wasmd module |
  │   └───────────────┘   │                          └───────────────┘
  └───────────────────────┘
              ↓
            done

• AnteHandler
  • Since the account doesn't have PubKey yet, for signature verification, SA SetPubKey will set a temporary PubKey for this account using the public_key parameter in the message.
  • After successful signature verification, SA decorator will remove temporary PubKey so that SA module can initiate contract with this account later.
• SA module
  • if the message meets all the checks, the module initiates a contract based on its parameters. The new contract will be linked to the pre-generated account (contract address will be same as account address). The module will then convert account to type SmartAccount and set PubKey for it. Finnaly, save it to auth module.

Required

• valid parameters.
• The account must have received the funds, so it can exist on-chain as BaseAccount type with an account number, sequence and empty public key before activated.
• The account address was not used to initiate any smart contract before.
• In some cases, we also allow reactivation of activated accounts that are not linked to any smart contracts.
• code_id must be in whitelist.
• actiavte message is the only message in tx.

Recover Account

We provide a smart account recovery way in case the user forgets the account's private key or wants to change the new one. Recovery is simply changing the PubKey of an account of type SmartAccount with the new setting. This is not a required function so users can choose whether their account is recoverable or not.

Message recover

The caller specifies the address to recover, the public key and provides credentials to prove they have the authority to perform the recovery.

type MsgRecover struct{
  // Sender is the actor who signs the message
  creator     string

  // smart-account address that want to recover
  address     string

  // New PubKey using for signature verification of this account, 
  // must be cosmos supported schemas
  public_key  Any

  // Credentials
  credentials string
}

The module makes a call to the recover method of contract that linked to smart account. If the message parameters meet the verification logic implemented in the contract, the smart account will be updated with the new PubKey.

• recover call

  type RecoverTx struct {
      Caller      string 
      PubKey      []byte
      Credentials []byte
  }
  

To illustrate this in a graph:

             tx
              ↓
  ┌───── Antehandler ─────┐
  │   ┌───────────────┐   │
  │   │  decorator 0  │   │
  │   └───────────────┘   │
  │   ┌───────────────┐   │
  │   │  decorator 1  │   │
  │   └───────────────┘   │ 
  │   ┌───────────────┐   │
  │   │  decorator 2  │   │
  │   └───────────────┘   │
  └───────────────────────┘
              ↓
      ┌────────────────┐
      │  msg recover   │ 
      └────────────────┘
              ↓
  ┌───────  module ───────┐
  │   ┌───────────────┐   │   `recover` sudo      ┌───────────────┐
  │   │   SA module   │---│---------------------->|  wasmd module |
  │   └───────────────┘   │                       └───────────────┘
  └───────────────────────┘
              ↓
            done

• SA Module
  • The SA module checks if the requested account is of type SmartAccount, if not, rejects it.
  • if recover call success, module will update new PubKey for account then save account to auth module.

Required

• valid parameters.
• Account with address must exists on-chain and has type SmartAccount.
• Account enables recovery function by implementing recover method in sudo entry point of linked smart contract.

Smart account Tx

Users can use smart accounts to sign and broadcast tx just like EOA.

Firstly, for pre-validation tx, the AnteHandler will trigger the smartcontract's pre_execute method, which is linked to the account. The user won't be charged for gas if it fails because the tx won't be allowed to join the mempool. Finnaly, following the execution of tx, the after_execute method will be used to ascertain the success or failure of tx.

The user won't be charged for the pre_execute or after execute calls because their consuming gas won't count to total gas used. However, they are limited by the MaxGasExecute param.

To illustrate this in a graph:

             tx
              ↓
  ┌───── Antehandler ─────┐
  │   ┌───────────────┐   │
  │   │ SA SetPubKey  │   │
  │   └───────────────┘   │
  │   ┌───────────────┐   │   `pre_execute` execute   ┌───────────────┐
  │   │ SA decorator  │---│-------------------------->|  wasmd module |
  │   └───────────────┘   │                           └───────────────┘
  └───────────────────────┘
              ↓
      ┌────────────────┐
      │      msg 0     │
      └────────────────┘
          ...........
      ┌────────────────┐
      │      msg 1     │
      └────────────────┘
              ↓
  ┌───────  module ───────┐
  │   ┌───────────────┐   │
  │   │    module 1   │   │
  │   └───────────────┘   │
  │   ┌───────────────┐   │
  │   │    module 2   │   │
  │   └───────────────┘   │
  └───────────────────────┘
              ↓
  ┌───── Posthandler ─────┐
  │   ┌───────────────┐   │   `after_execute` execute ┌───────────────┐
  │   │ SA decorator  │---│-------------------------->|  wasmd module |
  │   └───────────────┘   │                           └───────────────┘
  └───────────────────────┘
            done

• Antehandler
  • tx will be identified as signed by smart account. If true, it will be redirected to SA SetPubKey and SA decorator
  • smart account tx will go through the SA SetPubKey decorator instead of the auth SetPubKey decorator. This avoiding the check for similarity of Account Address and PubKey.

Required

• Signer is account with type SmartAccount

Ante/Post Handler

SetPubKey Decorator

Alternative for auth's SetPubkey Decorator

AnteHandler

func (d SetPubKeyDecorator) AnteHandle():
    if isActivationMsg:
        validateActivationMsg(tx.msgs)

        setTemporaryPubkey(tx.signer, tx.msgs[0].pubkey)
    else:
        if isSmartAccountTx:
            checkNilPubkey(tx.signer)
        else:
            return authante.SetPubkeyDecorator() // if is normal tx, run auth's SetPubkey Decorator

    return next() // run next ante handler

• validateActivationMsg(msgs)
  • Check if activation msg is the only one in the msgs
• setTemporaryPubkey(signer, pubkey)
  • Set pubkey for signer
• checkNilPubkey(signer)
  • Ensure signer account already has pubkey

SmartAccount Decorator

Run after auth's SigVerification Decorator for handling smart-account's tx

AnteHandler

func (d SmartAccountDecorator) AnteHandle():
    if isActivationMsg:
        HandleActivationMsg(tx) // run HandleActivationMsg func
    elif isSmartAccountTx:
        HandleSmartAccountTx(tx) // run HandleSmartAccountTx func

    return next() // run next ante handler

func HandleActivationMsg(tx):
    validateActivationMsg(tx.msgs)

    validateSignerAddress(tx.signer, tx.msgs[0])

    setSignerPubkey(tx.signer, tx.msgs.pubkey)

• validateActivationMsg(msgs)
  • Check if activation msg is the only one in the msgs
• validateSignerAddress(signer, msg)
  • Calculate address based on msg parameters
  • Compare new address with the signer's address
• setSignerPubkey(signer, pubkey)
  • Set pubkey to signer's account

func HandleSmartAccountTx(tx):

    checkAllowedMsgs(tx.msgs)

    callPreExecuteMsg(tx)

• checkAllowrdMsgs(msgs)
  • Check if all msg in msgs are allowed for smart-account by government
• callPreExecuteMsg(tx)
  • Call pre_execute method of smartcontract that linked with account for tx pre-validation

PostHandler

func (d AfterTxDecorator) PostHandle():
    callAfterExecuteMsg(tx)

    return next() // run next post handler

• callAfterExecuteMsg(tx)
  • Call after_execute method of smartcontract that linked with account for tx after-validation

ValidateAuthzTx Decorator

Run after SmartAccountTx Decorator for handling authz nested smart-account's msgs

(Ante/Post)Handler

func (d ValidateAuthzDecorator) (Ante/Post)Handle():
    for msg in tx.msgs:
        if msg is authz.MsgExec:
            validateNestedSmartAccountMsgs(msg.GetMessages())
    
    return next() // run next ante handler

func validateNestedSmartAccountMsgs(msgs):
    for msg in msgs:
        if msg.signer is typeOf(SmartAccount):
            call(Pre/After)ExecuteNestedMsg(msg)

        if msg is authz.MsgExec:
            validateNestedSmartAccountMsgs(msg.GetMessages())

• callPreExecuteNestedMsg(msg)
  • Call (pre/after)_execute method of smartcontract that linked with account for nested msg (pre/after)-validation

Params

Parameters are updatable by the module's authority, typically set to the gov module account.

• max_gas_execute: limit how much gas can be consumed by the pre_execute and after_execute method
• whitelist_code_id: determine which code_id can be instantiated as a smart account
• disable_msgs_list: list of msgs that smart account not allowed to execute

WASM

To be considered as smart account, smart contract linked with account must implement sudo methods, after_execute and pre_execute:

// sudo method
struct AfterExecute {
    //list of messages in transaction 
    pub msgs: Vec<Any>,
    // fee information of transaction
    pub call_info: CallInfo,
    // Is tx executed throught authz msg
    pub is_authz: bool
}

// sudo method
struct PreExecute { 
    //list of messages in transaction 
    pub msgs: Vec<Any>,
    // fee information of transaction
    pub call_info: CallInfo,
    // Is tx executed throught authz msg
    pub is_authz: bool
}

• Any: is json encoded message

  struct MsgData {
      pub type_url: String, // url type of message
      pub value:    Binary, // value of message
      // etc.
      //  MsgData {
      //      type_url: "/cosmos.bank.v1beta1.MsgSend",
      //      value: [...]
      //  }
  }
  

• CallInfo: is tx's fee information

  pub struct CallInfo {
      pub fee: Vec<Coin>,
      pub gas: u64,
      pub fee_payer: String,
      pub fee_granter: String,
  }
  

• pre_execute and after_execute method must not consume exceed max_gas_execute gas

Optional sudo method recover that activate the smart account recovery function

// sudo method
struct Recover {
    pub caller: String,
    pub pub_key: Binary,
    pub credentials: Binary,
}

smart account samples

x/smartaccount

• types/auranw is deprecated, used for v0.7.0 migration only, and will be removed later.