ERC-7405 A portable smart contract account (Portable Smart Contract Accounts)
Draft · Accounts & wallets · created 2023-07-26
A standard that lets a smart contract account be moved from one wallet service to another. Using a single newly generated migration key, it transfers the account in a manner similar to exporting a private key from a regular account.
Why it is needed
Smart contract accounts (SCAs), which operate via contract code, have become widely used since the introduction of the ERC-4337 standard, but unlike regular accounts (EOAs) that operate with a single private key, implementation code differs from wallet provider to wallet provider. As a result, they are not compatible with each other, and it is difficult for users to move an account to a different wallet service. A modular approach that assembles accounts like components has also been proposed, but its implementation cost is high and it imposes prerequisites on wallet implementations, making it unsuitable both for wallet providers who prefer their own implementation approach and for those who want to keep their contracts simple. The community currently has no general-purpose account migration standard usable with any implementation. This proposal defines a migration method that operates at the proxy (ERC-1967) layer, offering SCAs an experience similar to exporting an EOA via a private key or mnemonic.
What to implement
function cancelAccountMigration() external: Cancels an in-progress account migration. Must perform account self-verification.function deleteMigrationData(address randomOperator) external: Deletes the migration record. Must verify that the record's account is msg.sender.
In depth
The migration key and the random operator
A newly, randomly generated mnemonic or private key must be used for every migration. The address corresponding to this key's public key is the random operator address, which serves as the key for looking up the account in the registry. When a mnemonic is used, the derived migration private key follows the BIP 44 path m/44'/60'/0'/0/0'. For the user, this provides an experience similar to exporting an EOA via a private key or mnemonic, and using a new key each time prevents replay attacks or malicious signatures arising from reuse of the same key.
The MigrationOp signature scheme
A migration action must be signed with the migration private key over a MigrationOp struct. The struct consists of three fields: chainID, selector, and data. If selector corresponds to prepareAccountMigration(address,bytes), its value is 0x50fe70bd and data is abi.encode(randomOperator). If selector corresponds to handleAccountMigration(address,bytes,bytes), its value is 0xae2828ba and data is abi.encode(randomOperator, setupCalldata). The signature is produced using the ERC-191 scheme, and the MigrateOpHash being signed is computed as abi.encode(chainID, selector, data).
A shared registry at the protocol layer
To keep migration credentials simple and allow an account to be looked up directly using only the migration mnemonic or private key, a shared registry deployed at the protocol layer is required. The registry stores a MigrationData struct (account, createTime, lockUntil) keyed by the random operator address. setMigrationData must verify that migrationDataMap[randomOperator] is empty, and deleteMigrationData must verify that migrationDataMap[randomOperator].account is msg.sender. This prevents overwriting or deleting another account's migration record.
The migration procedure: preparation, handling, and cancellation
In the preparation step, prepareAccountMigration verifies the account's identity through the internal method _requireAccountAuth() (for example, for an ERC-4337 implementation, msg.sender == address(entryPoint)), checks the signature, confirms that the registry does not already hold the same random operator, then locks the account and records the migration with setMigrationData(randomOperator, lockUntil). The lock remains in place until either cancelAccountMigration or handleAccountMigration succeeds. In the processing step, handleAccountMigration must not verify the account's identity; instead it checks the signature and requires migrationData.account == address(this) and block.timestamp > migrationData.lockUntil. It then runs wallet A's pre-cleanup logic via _beforeWalletMigration(), swaps the ERC-1967 proxy implementation for wallet B's implementation, initializes it with address(this).call(initData), clears the registry record, and emits an AccountMigrated event. In the cancellation step, cancelAccountMigration verifies identity, then releases the lock and clears the record.
Storage layout rules
These rules prevent accidents where storage overlaps and values get overwritten when switching between different wallet implementations. An implementation contract must not declare state variables directly at the top of the contract; instead it must wrap all state variables in a single struct stored at a specific slot. The slot index must be unique per implementation. Namespaces may only use the characters A-Za-z0-9_, and it is recommended to include the wallet name and major version number in snake_case, as in foo_wallet_v1. The slot ID follows the format {namespace}.{customDomain} (for example, foo_wallet_v1.config), and the slot index is computed as bytes32(uint256(keccak256(slotID) - 1)).
Scope and relationship to modular approaches
This proposal is backward compatible with all SCAs based on the ERC-1967 proxy, and also applies to SCAs that do not use ERC-4337. Since it places no special preconditions on the implementation contract, it can be used broadly across diverse SCAs, does not interfere with existing implementations, and keeps operating costs low. Unlike modular systems that operate at the implementation layer, this works at the proxy layer, so the two approaches complement each other and can further increase interoperability and composability across the account abstraction ecosystem.
Proposal status
This document is a Draft status Standards Track ERC created on July 26, 2023, and assumes ERC-191 and ERC-1967. Because it is still in draft, details such as interfaces, selector values, and registry design may change, and it should be kept in mind that this is not yet a finalized standard. Developers reviewing an implementation should check the latest state in the original repository.
Things to watch out for
- Generate a new key for each migration: To prevent replay attacks or malicious signatures, every migration must use a freshly, randomly generated migration mnemonic or private key, along with its corresponding random operator address.
- Storage layout independence: Storage layout independence must be maintained across wallet implementations. Otherwise, storage can collide after migration.
- Timelock and prohibited actions while locked: A timelock is in place so that a malicious migration does not cause the owner to immediately lose access. During the lock period, the user can cancel the migration using the original account authentication. A locked account must not allow any form of asset transfer, external contract calls, attempts to change account authentication factors, or any action that could affect these three.
- Notification of migration: When performing a migration, the wallet provider should attempt to notify the account owner of the migration details through every available message channel.