Descriptor registries solve blind signing by adding a dependency
If a wallet cannot understand a contract call, give it a file explaining how to display one. The approach works, and it makes the display correctness depend on a file the wallet did not previously need.
What does a descriptor registry add to the trust boundary?
Whoever controls the descriptor. Clear-signing lets a wallet render a contract call by looking up a description of it, which is a real improvement over hex. The description comes from a registry, and a wrong description is more dangerous than no description at all.
- Descriptor-based clear signing is a genuine improvement over displaying a hash, and it introduces a new dependency.
- A poisoned or substituted descriptor produces a plausible, wrong rendering — which is worse than an obvious warning.
- Pinning the schema from the executing system removes the external lookup and the substitution opportunity with it.
Part of Digital asset custody
The problem descriptors address
A wallet receiving a contract call sees a target address and a blob of calldata. Without knowing the contract's interface it cannot say what the call does, so it displays a hash and a warning.
A descriptor supplies the missing knowledge: here is what this function is called, here are its parameters, here is how to display them for a human. The wallet renders something meaningful.
This is a real improvement over a hash, and the standards work behind it is worth supporting. The question is where the descriptor comes from.
The new dependency
| Question | Consequence |
|---|---|
| Who publishes the descriptor? | That party can influence what users see |
| How is it fetched? | A network dependency in the signing path |
| Is it authenticated? | If not, anything in the path can substitute it |
| What if it is missing? | Fall back to blind signing — or fail closed? |
| Who can update it? | An update changes the rendering for future signers |
Each of these has a good answer available. The concern is that a partial deployment — descriptors fetched over the network, cached, unauthenticated, with a fallback — is the easy implementation and the weak one.
Why a wrong rendering is worse than a warning
This is the crux.
# Without a descriptor
"Unknown contract call. Blind signing.
Hash: 0x9c1f8a3e..."
→ the user knows they are not verifying anything
# With a poisoned descriptor
"Approve token transfer
Amount: 100 USDC
Recipient: Treasury Operations"
→ the user believes they verified it
→ the call actually does something else entirelyAn honest warning preserves the user's accurate model of their own uncertainty. A confident wrong rendering destroys it, and the user proceeds with more confidence than in the unmitigated case.
The substitution paths
Assuming descriptors are fetched rather than pinned, the opportunities are the ordinary supply chain ones.
- Compromise of the registry or its publishing process
- A malicious or compromised descriptor author for a specific contract
- Interception between the wallet and the registry, if authentication is weak
- Cache poisoning, where a wallet retains a substituted descriptor
- An update that changes rendering for a contract already in use
None of these is exotic. They are the same categories that affect package registries and content delivery, applied to a file that determines what a user believes they are signing.
The alternative: pin from the executing system
If the system that will execute the action supplies the schema, and its hash is included in what gets signed, the lookup disappears.
statement = {
"schema_hash": "sha256:2b7d...4056", # pinned, in the signed data
"action": "treasury.transfer",
"asset": "USDC",
"amount": "100.00",
"to": "0x...",
"to_label": "Treasury Operations",
"chain_id": 1
}
# The schema that governs the rendering is identified inside
# the signature. A substituted schema produces a different
# hash and the verification fails.The trade-off is honest: this works where the executing system is known and can supply the schema. It does not solve the open case of a wallet encountering an arbitrary contract from an unknown source, which is the case descriptor registries were designed for.
Comparing the two fairly
| Descriptor registry | Pinned schema | |
|---|---|---|
| Covers arbitrary unknown contracts | Yes | No |
| External dependency at signing | Yes | No |
| Substitution risk | Present, mitigable | Eliminated by construction |
| Deployment effort | Ecosystem-wide | Per integrating system |
| Right for | Consumer wallets meeting new contracts | Institutional flows with known counterparties |
These are complementary rather than competing. A consumer wallet needs the registry approach because it genuinely meets arbitrary contracts. An institutional custody flow interacting with a known set of contracts does not, and should not accept the dependency.
If you deploy descriptors
- Authenticate descriptors with a signature from a party you have chosen to trust, not merely a TLS connection to a registry.
- Pin descriptor versions for contracts you use regularly, and treat updates as a change requiring review.
- Fail closed when a descriptor is missing. A fallback to blind signing is a fallback an attacker can induce.
- Display the descriptor's source and version, so a user can see what is rendering their transaction.
- Verify the descriptor matches the contract's actual interface, where the contract is verified and the interface is available.
A worked example: substitution paths
| Path | Effect |
|---|---|
| Malicious descriptor submitted | Wallet renders a benign description of a harmful call |
| Registry compromise | Same, at scale |
| Wrong descriptor matched | Honest error, identical outcome |
| Stale descriptor after upgrade | Renders the old semantics for new code |
| Pinned from the executing system | Rendering and execution come from the same place |
A warning tells the user to be careful. A confident wrong rendering tells them not to be, which is why the failure mode here is worse than the problem it replaced.
Objections and honest limits
“So descriptors are a bad idea.” No — they are a clear improvement over blind hex and should be deployed. The point is to be precise about what has been achieved: readability, not authenticity.
“Pinning from the executing system has its own trust assumption.” It does, and it is a narrower one. You are trusting the system that will perform the action to describe the action, rather than trusting a third party to describe someone else's code correctly.
If you deploy descriptors
- Know who can write to the registry. And what review applies.
- Handle the missing-descriptor case explicitly. Silence should not look like safety.
- Treat upgrades as descriptor-invalidating. Stale semantics render confidently.
- Prefer descriptors pinned by the executing system. Rendering and execution from one source.
- Sign what was rendered, not the payload. So the dispute has an answer.
Terms used here
- Clear signing
- Rendering a contract call in human-readable terms rather than presenting raw calldata.
- Descriptor
- A machine-readable description of how to render a contract call, resolved from a registry.
- Pinning
- Having the executing system supply the rendering, so description and execution share a source.
Frequently asked questions
Are descriptor registries a bad idea? No. They solve a genuine problem for wallets meeting arbitrary contracts. The concern is the new dependency and how partial deployments handle it.
Why is a wrong rendering worse than a warning? A warning preserves the user's accurate sense of uncertainty. A confident wrong rendering makes them believe they verified something they did not.
When is a pinned schema appropriate? When the executing system is known and can supply it — institutional flows with defined counterparties. It does not cover arbitrary unknown contracts.
What is the most important deployment rule? Fail closed when a descriptor is missing. A fallback to blind signing is one an attacker can induce.
Are descriptor registries worse than blind signing? No. They are a clear improvement. The caution is that a confident wrong rendering is more dangerous than an obvious warning.
What happens when a contract is upgraded? The descriptor can go stale and render old semantics for new code, confidently and without warning.
What does signing the rendering change? The user's signature covers what they actually read, so a later dispute is about a fact rather than an inference.
Where this fits in Manav
Manav signs the rendering itself — the exact bytes the person read — so approval and execution cannot silently differ.
Sources and further reading
- ERC-7730 — Structured data clear signing format
- EIP-712 — Typed structured data hashing and signing
- Published research on supply chain attacks against metadata registries.
- RFC 8785 — JSON Canonicalization Scheme