Clear signing upgradeable proxies without reading the chain

1The problem

ERC-7730 lets a hardware wallet show a human-readable intent for a contract call ("Withdraw 100 USDC to you"), using a descriptor file bound to the contract's address. Upgradeable proxies break the assumption behind it: the address stays the same while the code behind it can change at any time.

The device cannot read the chain, and it refreshes its descriptors only periodically (for example every hour). Between an upgrade and the next refresh it would keep showing an intent that may no longer be true.

2What's needed

• The hardware wallet makes no chain call. It sees only the descriptor and the transaction to sign.
• One transaction, one signature.
• Existing proxies and implementations work unchanged, and the proxy still sees the user as msg.sender.
• Any proxy type: transparent, UUPS, beacon, diamond.
• A descriptor must stop working on chain as soon as the code behind it changes, even if a device still holds it.

3Standards involved

4Entities

5How a call flows

1. The companion app builds the transaction. It is sent from the user's account to the user's account, with data execute(proxy, descriptorHash, withdrawCalldata).
2. The device checks it locally. The transaction is a call to its own address; descriptorHash is the hash of the descriptor it holds; that descriptor is signed by a trusted attester and bound to this proxy and chain. Then it displays the inner call as usual.
3. On chain, the delegate code checks the registry. If registry.isValid(proxy, descriptorHash) is false, the transaction reverts before the proxy is ever called.
4. Otherwise the user's account calls the proxy. The proxy sees msg.sender = the user and delegatecalls the implementation, exactly as a direct call would.

6Two entry points, one check

The check has to run outside the implementation, and the proxy still has to see the user as msg.sender. There are two ways to get both, and they can ship together: the same registry check behind two entry points.

Shipped together, the coverage is the union. The wallet picks the route per transaction:

The forwarder gets its own ERC-7730 file, identical to the delegate's except that it is bound to the forwarder's address. Two hazards come with the ERC-2771 route:

• One forwarder, many protocols. A bug in the canonical forwarder would expose every protocol that trusts it, so it must be tiny, immutable and audited.
• ERC-2771 combined with multicall. Together they let callers spoof msg.sender (the December 2023 incident, fixed in OpenZeppelin 4.9.4 and 5.0.1). A protocol adopting the forwarder must use a patched multicall or none.

The bottom-right cell cannot be closed. For a plain EOA to stay msg.sender without EIP-7702, the transaction has to go straight to the proxy, and then the only code that runs is the proxy and the implementation that just changed. Nothing outside the upgrader's control is left to perform the check.

7Descriptor lifecycle

The registry stores one flag per proxy and descriptor hash:

mapping(address target => mapping(bytes32 descriptorHash => bool)) public isValid;

Only the attester's address can call set. It can also revoke a hash by hand, for example if a descriptor turns out to be wrong.

8Minimal example

The protocol's descriptor: plain ERC-7730, unchanged

{
  "context": { "contract": { "deployments": [{ "chainId": 1, "address": "0xVaultProxy" }] } },
  "metadata": { "owner": "Example Vault" },
  "display": { "formats": {
    "withdraw(address token,uint256 amount,address to)": {
      "intent": "Withdraw from vault",
      "fields": [
        { "path": "amount", "label": "Amount", "format": "tokenAmount", "params": { "tokenPath": "token" } },
        { "path": "to", "label": "Recipient", "format": "addressName" }
      ]
    }
  }}
}

Its hash is keccak256(JCS(file)). That value goes into the registry and into the transaction.

The delegate's descriptor: one new parameter

{
  "context": { "contract": { "deployments": [{ "chainId": 1, "address": "0xClearSignDelegate" }] } },
  "display": { "formats": {
    "execute(address target,bytes32 descriptorHash,bytes data)": {
      "intent": "Verified call",
      "fields": [{
        "path": "data", "label": "Action", "format": "calldata",
        "params": {
          "calleePath": "target",
          "amountPath": "@.value",
          "descriptorHashPath": "descriptorHash"
        }
      }]
    }
  }}
}

calldata, calleePath and amountPath are standard ERC-7730. The highlighted parameter is the only addition: the file used to display the inner call must hash to that argument.

The transaction

from: 0xUser
to:   0xUser                         // the user's own account, running the delegate code
data: execute(
        target         = 0xVaultProxy,
        descriptorHash = keccak256(JCS(vault descriptor)),
        data           = withdraw(USDC, 100000000, 0xUser))

What the device shows

9Limits and cost