Add ERC-8176 descriptor attestation support

[manuelwedler]

Closes #61

Adds ERC-8176 attestation support: a wallet defines which auditors it trusts, and the library then formats only through descriptors that hold a valid attestation from one of them.

• New attestations policy on the shared resolver options (BaseResolverOptions): trustedAttesters, the auditor addresses the wallet trusts.
• New ExternalDataProvider.chainClient (ChainClient): a raw eth_call hook. The library uses it to read the revocation state itself (getRevokeOffchain(attester, uid) on the EAS contract on Ethereum mainnet). The library selects the contract, encodes the call, and decodes the result; the wallet only supplies the RPC connection. format() / formatTypedData() pass only the chain client to the resolver layer. The client is required when a policy is set.
• New src/attestations.ts: computeDescriptorHash (keccak256 of the RFC 8785 / JCS canonical JSON of the includes-resolved descriptor), verifyAttestation (offline checks: canonical schema UID, attested hash, EIP-712 domain pin to the mainnet EAS contract, expiration, ECDSA recovery, recomputation of the EAS v2 offchain UID; throws on the first failed check), isAttestationRevoked (the EAS read), and attestationPathForDescriptor (the registry's sigs/ file convention). computeDescriptorHash and attestationPathForDescriptor are public for custom resolvers and tooling.
• The policy is enforced in resolver.ts (applyAttestationPolicy) after includes resolution, on both the calldata and the EIP-712 path. Failures surface as NO_TRUSTED_ATTESTATION (with per-attester reasons) or ATTESTATION_OPTIONS_INCOMPLETE (missing chainClient, or a resolver without fetchAttestation); format() then falls back to rawCalldataFallback like NO_DESCRIPTOR. chainClient transport errors surface as DESCRIPTOR_FETCH_ERROR.
• The GitHub and filesystem resolvers implement the new optional DescriptorResolver.fetchAttestation (404 / ENOENT → no attestation). Bundled trusted-token descriptors are exempt from the policy.
• TypedDataDomain.chainId is now number | string, normalized with parseChainId everywhere it is read. The same type describes the EIP-712 domain of an attestation.
• utf8ToBytes replaces asciiToBytes (ASCII is a subset of UTF-8; the attestation hashes need full UTF-8).
• Without the attestations option the behavior is unchanged; README and GUIDE mark that mode as testing-only.
• New dependency @noble/curves 1.x (secp256k1 recovery; same family as the existing @noble/hashes, versions dedupe).
• Tests run the hash, signature, and UID checks against the registry's real Tether USD descriptor and its Cyfrin attestation, and cover edge cases (expired, revoked, tampered message/uid, wrong schema/hash/domain/version, wrong signer, includes-resolved hashing, chainClient call encoding and transport errors, trustedTokens bypass) with test-key-signed attestations.

Limitations (documented): only EAS offchain attestation version 2 with EOA signatures; onchain attestations and ERC-1271 contract attesters are out of scope.

TODO

• Create a follow-up issue for onchain attestations (attest() / attestByDelegation() on the EAS contract) and ERC-1271 contract attesters. Both can use the new ChainClient.

🤖 Generated with Claude Code

[kuzdogan]

Approve.

The code is correct and the tests are thorough. The EAS offchain UID, the signature recovery, the revocation read, and the JCS descriptor hash all match ERC-8176.

One caveat for rollout, not a code fix: against the live registry today, the gate rejects every descriptor that uses includes. The cause is external. The registry's attestations were made by clearsig, which hashes the raw descriptor file and does not resolve includes first. ERC-8176 requires the hash over the resolved descriptor, which is what this PR computes. So the two hashes differ and verification fails for 135 of the 181 attestations.

Filed upstream: Cyfrin/clearsig#16.

_{Posted with Claude Code}