ERC-7895 Sub Account Connection Wallet API (API for Hierarchical Accounts)
Draft · Accounts & wallets · created 2025-02-18
Allows an app to call wallet_addSubAccount to request that the universal wallet add or newly create an app-specific smart account as a sub account owned by the universal wallet.
Why it is needed
As more apps create their own dedicated embedded accounts, users must remember and manage multiple separate addresses. Hierarchical ownership, where one smart account owns another smart account, is already technically possible, but there has been no standardized way for an app to notify a user's universal wallet of the existence of such an embedded account. As a result, users cannot control app-specific accounts from a single universal wallet, and assets remain scattered across multiple accounts.
What to implement
addSubAccount: { account: CreateAccount | DeployedAccount | UndeployedAccount; }: A capability that can be included inside a wallet_connect call, adding a sub account immediately during the connection process.subAccounts: { address: `0x${string}`; factory?: `0x${string}`; factoryData?: `0x${string}`; }[];: A response format for querying the list of all sub accounts (including those already added) linked to a universal account.addSubAccount: { supported: true, keyTypes: ("address" | "p256" | "webcrypto-p256" | "webauthn-p256")[]; }: Included in the wallet_getCapabilities response, indicating whether the wallet supports adding sub accounts and which signing key types it supports.
In depth
Three account types
For CreateAccount, if no key is specified the wallet generates and manages the signing key itself, and the app can specify a signing key via a keys array if desired. DeployedAccount imports an already-deployed existing account into the wallet using only the address. UndeployedAccount is an account the app has already created but not yet deployed; it requires address, factory, and factoryData, and the wallet decides when to deploy it.
Ownership verification rules
For CreateAccount, the wallet SHOULD make the universal account the owner of the newly created account. For UndeployedAccount, the wallet SHOULD verify that the hierarchical relationship with the universal account actually holds by decoding factoryData or simulating the deployment.
Optionality of response fields
The factory and factoryData fields in the response are optional and SHOULD be included where possible. For an already-deployed account (DeployedAccount), these fields may be absent.
wallet_connect extension capabilities
In line with the connection RPC that incorporates the ERC-5792 capability specification, this proposal introduces the addSubAccount capability to add a sub account immediately at connection time, and the subAccounts capability to query the list of all sub accounts (including ones already added) linked to the universal account.
wallet_getCapabilities support declaration
An addSubAccount entry is added per chain to the ERC-5792 wallet_getCapabilities response, indicating whether it is supported and listing the signing key types the wallet accepts (address, p256, webcrypto-p256, webauthn-p256).
Background on the method name choice
Names such as wallet_linkAccount, wallet_importAddress, and wallet_addAddress, as well as splitting creation and tracking into separate RPCs, were also considered, but the proposal was consolidated into the single method wallet_addSubAccount. This name is explained as being more suitable since it also covers use cases involving EOAs.
A draft still subject to change
This proposal is currently in Draft status, so the method name, parameter structure, and capability details may change or discussion may be discontinued going forward.
Things to watch out for
- Interaction risk from growing capabilities: As functionality increases, unpredictable interactions can arise, which requires caution. App-specific accounts carry greater risk in terms of assets, but having the universal account own them can add extra security for the user's assets.
- Account data and privacy: Account data and shared capability information must be handled securely to prevent data leaks or man-in-the-middle attacks.