🏗️Smart Contract Architecture & Flow

You can view interactive account flowcharts here for the following actions:

• Create an Account

• Add an Abstraction Rule

• Execute a Cosmos Message

• Sign an EthUserOp

• Update User Account Contracts

An Obi account is set up by an Account Factory call, either by a user or by an entity pre-configuring an account which will be transferred to a user.

This creates a user_entry contract, which is minimal. This contract knows the address of its user_account contract, the main logic hub. In this way, the user_entry can execute an account upgrade by pointing to a new user_account contract with updated code – a sort of manual migration for chains where native migration/upgrade is not available.

The user account knows its owner and the address of its user_state contract, where all abstraction rules are stored. It also knows the addresses of various common logic contracts – in particular, the gatekeepers which check the various kinds of abstraction rules against incoming transactions.

Gatekeeper logic contracts include:

• gatekeeper_debt (for managing account fee debt)

• gatekeeper_message (allow/block/delay listing for specified actors and/or contracts and/or message contents)

• gatekeeper_spendlimit (allowances, budgets, inheritance)

Upcoming logic contracts include the following logic, which is currently included directly in user_account:

• EVM transaction/user operation parser

• Cosmos message parser

Message parsing is not required for all Obi features – chains without message parsing support can still include updatable Multikey ownership, unrestricted session keys, and final recovery/inheritance. However, the enforcement of spendlimits, allow/block lists, etc. requires message inspection by the contract in order to determine whether an existing abstraction rule allows the transaction.

In some implementations, gatekeeper_spendlimit interacts with an Asset Unifier contract, which in turn uses a Token/LP Asset Registry. This way, debt and spend limits can be denominated in a single asset, currently USD. For now, this is under centralized control using vetted lists of contract addresses, but control can eventually be transferred to governance, and users can add or block specific entries.

When signing for a target chain (not the home chain), the actor does not directly interact with user_entry. Instead, the actor calls Sign on the threshold signer contract and includes:

• partially completed offline signature shares (the signer will finalize with its share)

• if querying, proof that it controls an authorized keypair

• the user operation (EVM) or transaction for which the actor is requesting a signature

The threshold signer contract verifies the actor's identity and checks with the provided user_entry contract to verify that the user operation or transaction is allowed by some abstraction rule, authorizing the actor to perform the operation. It also checks that any necessary fee is included, if the transaction is a send. Assuming these checks pass, it completes the signature and returns it.