ERC-7754 Tamper-resistant Wallet Request (TWIST) (Tamperproof Extension Wallets API (TWIST))
Draft · Signatures & auth · created 2024-07-29
It allows a dapp to attach a digital signature to requests it sends to a wallet, and the wallet to verify the signature using a key published on the dapp's domain, confirming that the request was not tampered with in transit.
Why it is needed
Currently, the communication path between a dapp (blockchain app) and a wallet is vulnerable to man-in-the-middle attacks. If an attacker injects JavaScript code through a security hole in a webpage (XSS) or a malicious browser extension, they can intercept and alter requests the dapp sends to the wallet. For example, they could modify transaction data (calldata) to siphon off funds, alter the contents of an EIP-712 signature request, or obtain a signature that can be reused multiple times. Even if a user notices the possibility of tampering, there is effectively no way to prevent it. Because there is no chain of trust between the dapp and the wallet, users find it hard to fully trust even an honest dapp and are exposed to the risk of losing funds, while dapp operators risk reputational damage if an attack succeeds.
What to implement
type RequestPayload<Params> = { method: string; params: Params };: The original request to be delivered to the wallet, containing the RPC method name and its parameters.
In depth
Constructing the chain of trust
The chain is built with the dapp's domain certificate as the root of trust. The browser verifies the domain certificate, and a TXT field in the dapp's DNS record points to the URL where the JSON manifest is hosted. It is RECOMMENDED (SHOULD) that the manifest be placed at a well-known address such as /.well-known/twist.json. The manifest contains an array of objects shaped as { id, alg, publicKey }. The dapp signs the outgoing payload with a private key, then sends the original payload, the signature, and the public key id to the wallet via wallet_signedRequest, and the wallet processes the request as usual only after verifying the signature. This structure is similar to the role HTTPS plays on the web.
Key publication method and supported algorithms
Public keys are discovered via DNS records. The example method is writing TWIST=/.well-known/twist.json in a TXT record. This is similar to DKIM in RFC 6376, but using a manifest file allows supporting multiple algorithms and key pairs and makes future extension easier. Implementations MUST support the alg values ES256 and EdDSA from RFC 7518 section 3.1. Support for PS256, RS256, ES384, ES512, PS384, PS512, RS384, and RS512 is RECOMMENDED (SHOULD). Public keys must be represented as a hex string encoding of a DER-encoded X.509 SubjectPublicKeyInfo (SPKI) structure. Implementations are recommended to use SubtleCrypto, which is available in modern browsers.
Key cache should not exceed 2 hours
As is common practice with JWTs, a wallet may pre-fetch and cache a dapp's keys. However, since there is no key revocation mechanism, if a key is leaked, it could continue to be used until the cache expires. To reduce this risk, wallets SHOULD NOT cache a dapp's public key for longer than 2 hours. This keeps the window of vulnerability relatively short while remaining a manageable burden for both wallets and dapp operators.
wallet_signedRequest parameters
The new RPC method wallet_signedRequest takes three parameters. requestPayload is shaped as { method, params } and contains the original request to be executed (e.g., eth_sendTransaction and its parameters). signature is a hex string signature starting with 0x, and keyId is the identifier used to find the key for verification in the manifest. The dapp calls { method: 'wallet_signedRequest', params: [requestPayload, signature, keyId] } via the request method of the EIP-1193 provider.
Rules for the wallet's manifest lookup
When a wallet receives an EIP-1193 call, it MUST check whether a TWIST manifest exists for the domain in sender.tab.url. Because HTTP is vulnerable to DNS spoofing, HTTPS must be enforced, and the wallet must verify that the manifest is hosted on that domain. It is recommended to locate the manifest via the DNS TXT record, and the wallet MAY first try the /.well-known/twist.json location. The wallet MUST NOT follow redirects when fetching the manifest, since this could lead to an open redirect attack, and it is recommended to verify that the response's Content-Type header is application/json. If the domain has no TWIST configured, the request is processed as usual.
Signature verification and warning procedure
If the plain request method is used on a domain that has TWIST configured, the wallet SHOULD display a prominent, actionable warning to the user. If the user dismisses it, processing continues as usual; if the user cancels, the call MUST be aborted. When wallet_signedRequest is used, the wallet MUST verify integrity by checking that the keyId exists in the manifest and calling crypto.verify(alg, key, signature, requestPayload) using the alg and publicKey of that key record. If the signature is invalid, the wallet must display a warning, proceed by calling request with the requestPayload if the user dismisses it, and abort if the user cancels. If the signature is valid, the wallet must call request with the requestPayload. It MAY also display a visual indicator that the interaction is signed.
UX that warns but does not block
Much like the padlock icon for HTTPS, it is good practice for wallets to show a prominent indicator on domains that have TWIST configured. This lets users immediately recognize that the interaction between the dapp and wallet is secure, which encourages dapp developers to adopt TWIST and makes the ecosystem safer overall. For unsafe requests, whether a plain request is used on a domain that has TWIST configured or a signature does not match, the wallet warns but does not block. A well-written warning increases transparency and lets the user decide for themselves whether to cancel or proceed at their own risk.
A proposal still at the draft stage
The original text explains that this proposal only adds to, and does not alter, the existing functionality of EIP-712 and EIP-1193, giving it backward compatibility, and that it is modeled on existing solutions like DKIM, making it easy for both wallets and dapps to implement. However, since it is currently in Draft status, the content of this proposal is subject to change.
Things to watch out for
- Replay attacks are not separately prevented: Signing the payload guarantees data integrity but does not by itself prevent replay attacks. The same signed payload could be reused multiple times, or across multiple chains. Replay over time can typically be prevented with a transaction nonce, and cross-chain replay can be prevented with EIP-712 signTypedData. Read-only methods that are protected by neither offer very low value to an attacker, so the original text does not currently recommend a specific anti-replay mechanism, noting that if one becomes necessary, protections similar to JWT could be added via the manifest's extensibility.
- The manifest itself can be attacked: Because an attacker could spoof a DNS entry to serve their own manifest, wallets must only fetch the manifest from 'https://${sender.tab.url}/${pathFromDNSRecord}'. An attacker could also exploit another vulnerability in the dapp to upload a malicious manifest to the dapp's domain; to guard against exploitation of an open redirect, the wallet must not follow redirects, and to guard against a file being covertly uploaded, it is recommended to verify that the content-type header is application/json.