Primitives

Learn about the primitives (component parts) that provide functionality for Circle’s Programmable Wallets: 

• Users
• Wallets
• Wallet sets
• Monitored token list
• Transactions

Users

When using user-controlled wallets, the user represents one of your application’s end-users. The userIdprovided at the time of account creation is tied to all end-users' associated wallets, tokens, and transactions. 

Wallets

A web3 wallet is a tool for storing a user’s private keys, which provide access to their tokens, including NFTs. A wallet is a UUID that combines an address and its metadata, all of which are stored on a blockchain. 

Wallets have the following attributes: 

• A wallet has an address on a blockchain. Multiple wallets can share the same address on different EVM blockchains.

• A wallet has a custody type (custodyType) that defines whether the user or developer has the control of invoking the private key of the wallet

  • A user-controlled wallet can be created from APIs and SDKs paired with a wallet set. Additionally, for the use case that an app supports additional blockchains, new user-controlled wallets can be created from the existing wallet set of the user.
  • A developer wallet must be created from a wallet set. Multiple wallets can be created from the same wallet set.

Wallet sets

A Circle wallet set is a set of wallets created and managed by a unique cryptographic private key. Wallet sets use the HD wallet setting on supported blockchains.

Wallet sets have the following attributes: 

• A wallet set can contain one or many wallets.

• A wallet set can have wallets with addresses on multiple blockchains. On EVM chains, a wallet set can have wallets on different chains sharing the same address. 

• A wallet set has a custody type (custodyType). You can use it to create wallets in which custody is either developer-controlled or user controlled, but not both.

  • You can create a user-controlled wallet directly from the API and SDK without creating the wallet set first. The newly created user-controlled wallet will be paired with a unique wallet set.  
  • You can only create a Developer wallet from a wallet set. This requirement prevents creating multiple wallet sets unintentionally when you need only one Developer wallet set.

Transactions

In Circle’s Programmable Wallets, a transaction represents either a transfer of tokens, inbound or outbound, in a wallet on the blockchain or the execution/deployment of smart contracts. 

A Transaction contains an Operation field that defines the use case for the transfer. The following table describes the operations and the relationship between the possible field value and the corresponding destination address:

Transactions also include metadata that outlines their state. Once a transaction is created, Circle starts monitoring the transactions on its respective networks containing a state field. 

You can find more information about transaction states in this guide.