Smart Wallets

Smart Wallets are a core component of the Ava Protocol ecosystem that facilitate on-chain interactions for automated workflows.

Smart Wallets are a core component of the Ava Protocol ecosystem that facilitate on-chain interactions for automated workflows. These deterministic contract wallet addresses are generated based on a factory contract address and a salt value, enabling workflows to execute blockchain transactions in a secure and predictable manner.

For information about how to create workflows that use smart wallets, see Workflow System and Nodes.

1. Smart Wallet Architecture#

Smart Wallets in the Ava SDK are deterministically derived contract addresses that act as on-chain identities for your workflows. They are counterfactual in nature, meaning their addresses can be computed before deployment.

Smart wallets are computed using a factory contract address and a salt value. The factory follows the ERC-4337 account abstraction standard to facilitate deterministic address generation.

Sources:

2. Smart Wallet Properties#

A Smart Wallet contains several key properties that provide information about the wallet and its associated workflows.

PropertyTypeDescription
addressstringThe derived Ethereum address of the smart wallet
factorystringThe factory contract address used to derive the wallet
saltstringThe unique salt value used in address derivation
totalTaskCountnumberTotal workflows created with this wallet
activeTaskCountnumberCurrently active workflows
completedTaskCountnumberSuccessfully completed workflows
canceledTaskCountnumberCanceled workflows
failedTaskCountnumberFailed workflows

Smart wallets maintain counters for different workflow states, providing an easy way to track activity across all workflows associated with a particular wallet.

Sources:

3. Creating and Retrieving Smart Wallets#

The client interface provides methods to create and retrieve smart wallets. The address is derived deterministically, which means the same salt and factory address will always produce the same wallet address.

To retrieve a smart wallet, you need to provide a salt value and have a factory address configured either in the client or passed as an option.

Sources:

4. Code Example: Retrieving a Smart Wallet#

To retrieve a smart wallet, you first need to initialize a client with the appropriate configuration and then call the getWallet method:

  1. Initialize the client with an endpoint and factory address
  2. Authenticate the client
  3. Call getWallet with a salt value

The salt value can be any string, including numeric values or timestamps. The same salt and factory address will always produce the same wallet address.

Sources:

5. Smart Wallet and Workflow Relationship#

Smart wallets serve as the on-chain identity for workflows. When creating a workflow, you specify the smart wallet address that will be used to execute the workflow's on-chain actions.

When a workflow is submitted, the smart wallet's task counters are updated to reflect the new active task. As the workflow changes state (completed, canceled, failed), the corresponding counters are updated.

Sources:

6. Managing Smart Wallet Task Statistics#

The smart wallet keeps track of various statistics related to workflows (tasks) executed by the wallet. These statistics include:

  1. Total task count - the number of workflows created
  2. Active task count - workflows that are currently running
  3. Completed task count - workflows that have completed successfully
  4. Canceled task count - workflows that have been canceled
  5. Failed task count - workflows that have failed

These statistics update automatically based on workflow state changes:

  • When a workflow is submitted, totalTaskCount and activeTaskCount increment
  • When a workflow completes, activeTaskCount decrements and completedTaskCount increments
  • When a workflow is canceled, activeTaskCount decrements and canceledTaskCount increments

Sources:

7. Best Practices for Smart Wallet Management#

Salt Generation Strategies#

Choosing an appropriate salt value is important for managing your smart wallets:

  • Use deterministic salts when you need to retrieve the same wallet address consistently
  • Use timestamps or random values when you need a unique wallet for each deployment
  • Consider using environment variables or configuration values for salts in production environments

Factory Address Management#

The factory address is critical for correct wallet address derivation:

  • Set the factory address when initializing the client
  • Ensure the factory address is valid before attempting to get a wallet
  • You can override the client's factory address by providing it directly in the getWallet options

Sources:

8. Common Issues and Troubleshooting#

Invalid Factory Address#

If you encounter an error related to an invalid factory address, ensure:

  1. The factory address is a valid Ethereum address
  2. The factory address is set either in the client or provided in the options
  3. The factory address points to a deployed and compatible factory contract

Incorrect Wallet Address#

If the wallet address is not what you expected:

  1. Verify you're using the correct salt value
  2. Ensure the factory address matches the one used previously
  3. Check that you're not mixing different environments (testnet vs. mainnet)

Sources: