x/accounts for dummies

x/accounts allows us to create new account types that can go from very basic to very complex. Accounts can have their own store (not by account type but by account) and ways of executing messages and authenticating the sender.

This doc is for new comers to understand the basics. Implementation details are ignored.

What's a bundler?

It's a participant of the network, similar to a relayer in IBC. So it's who sends the actual messages to the chain, basically broadcasts and pays for the tx.

Who can be a bundler?

Anyone can be a bundler.

• A validator providing "broadcasting as a service".
• A multisig interface that does the signature aggregation.
• The same sender.

Which transactions a bundler will send?

It will send a list of UserOperation inside a tx (MsgExecuteBundle). The bundler will decide which transactions (UserOperation) to put in its txs based on arbitrary reasons.

An example would be a Validator that wants to provide free transaction broadcasting for its delegators. So it will add any UserOperation that its delegators send to it off-chain to send on a periodic MsgExecuteBundle.
The check of what to add and what not to add is fully off-chain.

What kind of checks can a bundler do?

Pretty much anything, it could be the sender, what the messages being sent are (what types and what they are doing), etc.

But the most important thing bundlers might look into are the "Bundler Payment Messages" (bundler_payment_messages). These are messages that will get executed before the "Execution Messages" (execution_messages,), in these messages the sender of the operation can include any form of payment required by the bundler.

An example of this would be a bundler that requires a payment of 1USDC per message being executed. So a user will send an operation looking like this:

UserOperation {
  bundler_payment_messages: [{MsgBankSend 3USDC to BundlerAddress}],
  execution_messages: [{MsgBankSend whatever}, {Msg2}, {Msg3}]
}

What the bundler will do is check if the bundler_payment_messages includes a x/bank Send message sending funds to its account for the amount of 3USDC (given that there are 3 execution messages). All of these checks are done off-chain.

What's a UserOperation?

It's like a transaction envelope. It contains all the necessary information to execute a bunch of messages. These are executed by sending a list of them inside a MsgExecuteBundle.

sender: the account that's going to be used to execute the messages (doesn't need to be the signer of the actual tx being broadcasted, see the bundler section above).

authentication_data and authentication_method: these are going to be used by the account implementation to ensure that the sender is who he says he is. In a case of a Multisig implementation, authentication_data would include the members' signatures, for example.

bundler_payment_messages: the messages to pay the bundler for its service. This could be empty if I'm acting as my own bundler.

execution_messages: the actual messages I want to execute.

Example: A multisig implementation

As said previously, an account can store stuff. For a multisig account we would store participants:

type MultisigAccount struct {
  Members collections.KeySet[crypto.PubKey]
  MinimumSigners collections.Item[int]
}

In our multisig we'll expect that at least MinimumSigners of Members send a signature for any given execution.

An account is initialized by executing an Init message in the implementation. This message can contain any necessary data for setting up the account, in our case it will be the initial members and the minimum amount of signatures needed.

message MsgInit {
  repeated bytes pub_key_bytes = 1;
  uint32         min_signers   = 2;
}

Notes on account initialization

When an account is initialized, it is given an address BEFORE calling the implementations' Init method. This address is derived from a hash of a sequenced number (TODO: add link).
The x/accounts module will pass a prefixed store using the address in order to provide a separate store for each account (which I think it's pretty cool btw).

Now our Init method is going to be called, so we have to set the members and min signers. An implementation of this would look like:

func (a MultisigAccount) Init(ctx context.Context, msg *MsgInit) (*MsgInitResponse, error) {
    for _, m := msg.PubKeyBytes {
      member := parseOrDoWhateverIsNeeded(m)
      a.Members.Set(member)
    }

    a.MinimumSigners.Set(msg.MinSigners)
    
    return nil, nil
}

Once the account is initialized we can execute UserOperations with it.

Authenticate

When executing UserOperations, the first step x/accounts takes is to execute the Authenticate method in the accounts implementation.

func (a MultisigAccount) Authenticate(ctx context.Context, msg *account_abstractionv1.MsgAuthenticate) (*account_abstractionv1.MsgAuthenticateResponse, error) {
    // here we use a.Members to check if signers are OK,
    // parse signatures from AuthenticationData and check if
    // they are correct by whatever signature method we've chosen.
    signatures := parseSignatures(msg.UserOperation.AuthenticationData)
    ok := checkSignatures(msg.UserOperation, signatures)
    if !ok {
        return nil, errors.New("bad sigs!")
    }
    // ...
}

The cherry on top: updating an account's members (modifying its store)

As said in the previous paragraphs accounts have their own state, and this means it can also be modified. In our example we are holding the members of This is done through a message:

func (a MultisigAccount) RotateMembers(ctx context.Context, msg *MsgRotateMembers) (*rotationv1.MsgRotatePubKeyResponse, error) {
    // if we are executing this, we know that the multisig signed this message as Authenticate has already been executed correctly.
	return nil, a.Members.Set(msg.NewMembers)
}

Summary

Off chain:

1. A user (or group of users) form a UserOperation
   a. Sign the UserOperation it with a custom method (could be just signing over specific fields or whatever the implementation calls for)
   b. They aggregate the signatures into the authentication_data field.
2. Any of the users of the group can act as a bundler and sends the MsgExecBundle once the necessary amount of signatures have been gathered.

On chain:

1. The Authenticate method in the Multisig implementation is executed, signatures are checked, etc.
2. PayBundler is executed. In our case a member of the multisig was supposed to send the tx for free so this was left empty, and nothing was executed
3. ExecuteMessages is executed, the messages are executed and a response is provided.

Left out ExecuteMessages and PayBundler

Implementing these methods allow a finer control over execution. So an implementation could come up with "pre-exec" and "post-exec" actions and such.
I feel this is not mandatory to understand the basics of x/accounts.