ERC-7738 Permissionless script registry
Draft · Other · created 2024-07-01
Defines a public registry where anyone can register and look up the location (URI) of execution scripts linked to a contract, given only the contract address. Wallets or apps can find and download scripts from here.
Why it is needed
Previously, linking a script to a token contract required building in the ERC-5169 lookup function from the time the contract was created, or providing an upgrade path to add it later. If an already-deployed contract lacks that function, there is no way to link a script to it. Yet collecting the script list on a central server creates its own problem: that server's security must be managed separately, and a specific organization ends up acting as gatekeeper of the database. This standard places a single registry contract on chain that anyone can use, allowing script locations to be uploaded and found without modifying the contract.
What to implement
event ScriptUpdate(address indexed contractAddress, string[] newScriptURI);: An event emitted when a contract's script URI is updated. A wallet implementing this interface can watch this to update its cached script.function scriptURI(address contractAddress) external view returns (string[] memory);: Returns the list of script URIs registered for the given contract address.function setScriptURI(address contractAddress, string[] memory scriptURIList) external;: Registers or updates the list of script URIs for the given contract address and emits a ScriptUpdate event.
In depth
Relationship with ERC-5169
ERC-5169 is a method where the contract itself provides the client script lookup function. This approach requires implementing that interface when the contract is created, or allowing an upgrade path. ERC-7738 moves the lookup function out to a separate registry outside the contract, allowing even contracts written without ERC-5169 to link scripts on their own. It also does not require a central online server, so there is no need for an organization to manage server security or act as a database gatekeeper.
Multi-chain singleton structure
The registry contract supplies prototype scripts and certified scripts. It operates as a multi-chain singleton instance deployed at the same address across the chains it supports. The registry returns a set of URI links for a given contract address, and these links point to script programs that wallets, viewers, and mini-dapps can fetch. Pointers can be set permissionlessly by anyone through the registry's setter.
Implementation requirements
The implementing contract MUST implement the IERC7738 interface, and MUST emit a ScriptUpdate event when a script is updated. The list returned by scriptURI SHOULD be ordered so that entries uploaded by that contract's ERC-173 owner() come first, because simple wallet implementations pick the first scriptURI in the list. A means of paging through entries SHOULD also be provided in case there are many scriptURI entries.
Reference implementation and minimal implementation
An actual registry implementation is deployed at address 0x0077380bCDb2717C9640e892B9d5Ee02Bb5e0682 across multiple mainnet, L2, and testnet chains, and can be registered either by calling the setScriptURI function directly or via the accompanying ethers script. The included minimal implementation, DecentralisedRegistry, checks in setScriptURI that the list is not empty, and if the caller is neither the target contract's owner() nor an existing registrant, adds them to the address list (addrList). scriptURI returns entries uploaded by the owner first, followed by the entries from the other registrants.
Test cases
Test cases are included in NFTRegistryTest.test.ts, with the contract, deployment script, and registry script provided along with the test scripts. You can clone the repository, install hardhat, and run it with npx hardhat test.
Proposal status
This proposal is still in Draft status. Since the content may change going forward, you should check the latest source text when implementing.
Things to watch out for
- Verifying a script with the owner's signature: If the target contract implements the ERC-173 Ownable interface, after fetching the script you can verify that the signature matches owner(). For a TokenScript, you can use the SDK or an online verification service, or extract the signature from the XML and run ecrecover against the keccak256 hash of the script to check the signing key's address.
- Alternatives for contracts without Ownable: If a contract does not implement Ownable, you can check the deployment key via a third-party API or block explorer and compare it against the signature, have the hosting app pre-authenticate the signing key with a built-in keychain, or have a governance-token-based script committee authenticate key setup and verification requests.
- Treatment of unverified scripts: For scripts that fail to meet these verification criteria, wallets should exercise caution about use on mainnet, leaving it to the discretion of the app or the user. On testnets, wallet providers may, at their discretion, allow the script to run.