TypeScript integration gaps found while building the live bind app #116

Building the live end-to-end bind app (#72, ts/apps/bind) meant writing everything an outside application needs to get from a ceremony result to a mined IdentityRegistry.bind. These are the TypeScript gaps that work turned up.

Packages

1. @libid/ceremony, @libid/ledger and @libid/popup are private. An application outside this monorepo can't install them.
2. The ceremony pins a @libid/contracts version that can lag the deployed chain. Nothing tells an integrator which contracts, circuits and verifiers a ceremony build needs (see "Versions" below).

From a ceremony result to a bind transaction

3. There is no EVM LedgerId. Every application rebuilds the Chain ID hash (keccak256(U256BE(chainId)), chain-profiles §3.1) by hand.

4. There is no payload encoder. The application must know each verifier's struct and encode it as one ABI tuple:

   • TlsNotaryProof for GitHub and X;
   • GoogleProof for Google.

   docs/client.md stops at "hand to your ledger adapter". ts/apps/bind/src/evm.ts has working encoders that could be published.

5. Nothing dispatches on the platform. Each platform family needs its own encoder, and there is no single "result to payload" function.

6. One payload's fields come from three places:

   • most of it from oauthProof;
   • Google's client identifier from identity.oauthClientId;
   • the operation domain and transaction data, which oauthProof does not carry, so the application must keep them itself.

   None of this is documented.

7. Naming mismatch: an attestation's signature in TypeScript is proof in the Solidity struct.

8. Narrowing doesn't work: checking result.identity.platformId does not narrow result.oauthProof's type, so the application needs casts.

9. bind's verifierVersion is easy to confuse. It is the registry's verifier slot, not the proof's platformCeremonyVersion. The two are both 1 today, so mixing them up works until it doesn't.

10. The Authorization Digest helper is not exported, so an application cannot check a proof against its inputs before submitting.

Errors

11. The verifiers' error ABIs are not exported. A failed bind shows a bare selector, such as 0xa493bc37 (AttestationAhead) or SumcheckFailed(), that viem cannot decode.

Versions

12. No compatibility signal between a ceremony build and the verifier artifacts it needs.
    • Main's ceremony proves with the libid-circuits v0.6.0 circuits. A chain deployed with an older libid-deploy reverts every bind with SumcheckFailed().
    • Nothing checks or states the pairing up front.
13. Breaking client API changes arrive without a signal. client.connect now generates the connection id and client.new takes none; we found it through a broken build.

Already addressed elsewhere

• viem at load time: @libid/contracts always loaded viem, even for handle normalization. Fixed by @libid/contracts/handle in libID-contracts popup: mobile-WebKit flake in close-right-after-navigate (CI only) #86.
• Two copies of @libid/contracts: different version pins broke instanceof HandleError. One catalog pin, and HandleError re-exported from @libid/ens (feat(ens): @libid/ens, the ENS name of a handle #109).
• Handle → ENS name: @libid/ens (feat(ens): @libid/ens, the ENS name of a handle #109).

Suggested first steps

• Publish the packages, or say which ones are meant for integrators.
• An EVM ledger adapter: evmLedger(chainId, notary) plus encodeBindPayload(result, operationDomain, transactionData) for every platform, built from the generated verifier ABIs so it can't drift.
• Export the digest helper and the verifier error ABIs.
• State the circuit and verifier version a ceremony build requires, and check it against the chain before proving.