@coordination-network/user-client 0.0.1

package/dist/index.js

@@ -0,0 +1,412 @@
+import { encodeMetaStealthAddress, META_STEALTH_ADDRESS_LENGTH, validateMetaStealthAddress, computeNetworkId, deriveKeys, metaStealthAddressUri } from '@coordination-network/identity';
+export { InvalidMetaStealthAddressError, metaStealthAddressUri as displayMetaStealthAddress } from '@coordination-network/identity';
+import { keccak_256 } from '@noble/hashes/sha3';
+import { hexToBytes as hexToBytes$1, bytesToHex as bytesToHex$1, concatBytes as concatBytes$1, utf8ToBytes } from '@noble/hashes/utils';
+import { secp256k1 } from '@noble/curves/secp256k1';
+
+/** Base error class for all errors thrown by this package, discriminated by `code`. */
+class UserClientError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = "UserClientError";
+        this.code = code;
+    }
+}
+class SubmissionFailedError extends UserClientError {
+    constructor(message, cause) {
+        super("SUBMISSION_FAILED", message);
+        this.name = "SubmissionFailedError";
+        if (cause !== undefined) {
+            // Non-enumerable, matching the standard Error.cause. Provider errors hold circular
+            // transport graphs, so an enumerable copy makes JSON.stringify throw inside a
+            // caller's error handler and drags the provider's URL into its logs.
+            Object.defineProperty(this, "cause", { value: cause, writable: true, configurable: true });
+        }
+    }
+}
+class RegistryReadFailedError extends UserClientError {
+    constructor(message, cause) {
+        super("REGISTRY_READ_FAILED", message);
+        this.name = "RegistryReadFailedError";
+        if (cause !== undefined) {
+            Object.defineProperty(this, "cause", { value: cause, writable: true, configurable: true });
+        }
+    }
+}
+
+/** ERC-6538 scheme 1 (secp256k1 stealth addresses), the schemeId field of the consent struct. */
+const SCHEME_ID = 1;
+/** networkId is a bytes32 on chain, and abi.encode splices it in as one word. */
+const NETWORK_ID_LENGTH = 32;
+/** r || s || v, the 65-byte Ethereum signature layout. */
+const SIGNATURE_LENGTH = 65;
+/** keccak256 output, the only thing this package will sign. */
+const DIGEST_LENGTH = 32;
+/** Ethereum transaction hash, as HttpSubmissionError's 201 branch expects it. */
+const TX_HASH_LENGTH = 32;
+/** Wire-format version of RegistrationRequest. */
+const REQUEST_VERSION = "v1";
+const IDENTITY_REGISTRY_DOMAIN_NAME = "IdentityRegistry";
+const IDENTITY_REGISTRY_DOMAIN_VERSION = "1";
+/** Signed by the user as consent to register; the member server verifies it, the contract never reads it. */
+const REGISTER_IDENTITY_TYPE = "RegisterIdentity(bytes32 networkId,uint256 schemeId,bytes metaStealthAddress)";
+const EIP712_DOMAIN_TYPE = "EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)";
+
+/** Encodes a device's spending and viewing keys as its ERC-6538 scheme-1 meta-stealth address. */
+function metaStealthAddressFromKeys(keys) {
+    return encodeMetaStealthAddress({
+        spendingPublicKey: keys.spending.publicKey,
+        viewingPublicKey: keys.viewing.publicKey
+    });
+}
+
+/** Parses a 0x-prefixed hex string into bytes. Throws on missing prefix, odd length, or non-hex chars. */
+function hexToBytes(hex) {
+    if (typeof hex !== "string" || !hex.startsWith("0x")) {
+        throw new UserClientError("INVALID_INPUT", `Expected a 0x-prefixed hex string, got ${typeof hex}`);
+    }
+    const body = hex.slice(2);
+    if (body.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(body)) {
+        throw new UserClientError("INVALID_INPUT", `Malformed hex string of length ${body.length}`);
+    }
+    return hexToBytes$1(body);
+}
+function bytesToHex(bytes) {
+    return `0x${bytesToHex$1(bytes)}`;
+}
+function concatBytes(...arrays) {
+    return concatBytes$1(...arrays);
+}
+/** Big-endian 32-byte word encoding of a non-negative safe-integer uint256, as abi.encode would produce. */
+function numberToWord(value) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new UserClientError("INVALID_INPUT", `Expected a non-negative safe integer, got ${typeof value} ${value}`);
+    }
+    const word = new Uint8Array(32);
+    let remaining = BigInt(value);
+    for (let i = 31; i >= 0 && remaining > 0n; i -= 1) {
+        word[i] = Number(remaining & 0xffn);
+        remaining >>= 8n;
+    }
+    return word;
+}
+/** Left-pads a 20-byte address into a 32-byte word, as abi.encode would produce. */
+function addressToWord(address) {
+    const addressBytes = hexToBytes(address);
+    if (addressBytes.length !== 20) {
+        throw new UserClientError("INVALID_INPUT", `Expected a 20-byte address, got ${addressBytes.length} bytes`);
+    }
+    const word = new Uint8Array(32);
+    word.set(addressBytes, 12);
+    return word;
+}
+
+const EIP712_DOMAIN_TYPEHASH = keccak_256(utf8ToBytes(EIP712_DOMAIN_TYPE));
+const REGISTER_IDENTITY_TYPEHASH = keccak_256(utf8ToBytes(REGISTER_IDENTITY_TYPE));
+/** Every input is already a 32-byte word, so concatenating them is what abi.encode would emit. */
+function hashEncodedWords(...words) {
+    return keccak_256(concatBytes(...words));
+}
+function identityRegistryDomainSeparator(domain) {
+    const nameHash = keccak_256(utf8ToBytes(IDENTITY_REGISTRY_DOMAIN_NAME));
+    const versionHash = keccak_256(utf8ToBytes(IDENTITY_REGISTRY_DOMAIN_VERSION));
+    return bytesToHex(hashEncodedWords(EIP712_DOMAIN_TYPEHASH, nameHash, versionHash, numberToWord(domain.chainId), addressToWord(domain.verifyingContract)));
+}
+function registerIdentityStructHash(networkId, metaStealthAddress) {
+    const networkIdWord = hexToBytes(networkId);
+    if (networkIdWord.length !== NETWORK_ID_LENGTH) {
+        throw new UserClientError("INVALID_INPUT", `Expected a ${NETWORK_ID_LENGTH}-byte networkId, got ${networkIdWord.length} bytes`);
+    }
+    const metaHash = keccak_256(hexToBytes(metaStealthAddress));
+    return bytesToHex(hashEncodedWords(REGISTER_IDENTITY_TYPEHASH, networkIdWord, numberToWord(SCHEME_ID), metaHash));
+}
+/**
+ * The digest the user signs as consent to register this meta-stealth address at this registry on
+ * this chain. The member server verifies it before submitting; the contract never reads it.
+ */
+function registerIdentityDigest(domain, networkId, metaStealthAddress) {
+    const domainSeparator = hexToBytes(identityRegistryDomainSeparator(domain));
+    const structHash = hexToBytes(registerIdentityStructHash(networkId, metaStealthAddress));
+    return bytesToHex(keccak_256(concatBytes(Uint8Array.from([0x19, 0x01]), domainSeparator, structHash)));
+}
+
+/** Returns a 65-byte `r || s || v` signature, with `v = 27 + recovery id` as the contract expects. */
+function signRegisterIdentity(accountPrivateKey, digest) {
+    const digestBytes = hexToBytes(digest);
+    if (digestBytes.length !== DIGEST_LENGTH) {
+        // Exported, so refuse to sign anything that is not a digest this package produced.
+        throw new UserClientError("INVALID_INPUT", `Expected a ${DIGEST_LENGTH}-byte digest, got ${digestBytes.length}`);
+    }
+    const signature = secp256k1.sign(digestBytes, hexToBytes(accountPrivateKey), { lowS: true });
+    return bytesToHex(concatBytes(signature.toCompactRawBytes(), Uint8Array.from([27 + signature.recovery])));
+}
+function buildRegistrationRequest(keys, domain) {
+    const metaStealthAddress = metaStealthAddressFromKeys(keys);
+    const digest = registerIdentityDigest(domain, keys.networkId, metaStealthAddress);
+    return {
+        version: REQUEST_VERSION,
+        networkId: keys.networkId,
+        schemeId: SCHEME_ID,
+        metaStealthAddress,
+        chainId: domain.chainId,
+        verifyingContract: domain.verifyingContract,
+        signature: signRegisterIdentity(keys.account.privateKey, digest)
+    };
+}
+/**
+ * Whether a member server pinned to `expected` should accept the request: field widths, a
+ * well-formed meta-stealth address, the domain, and a signer matching the full `networkId`.
+ *
+ * `expected` is required because the domain inside a request is attacker-controlled — verifying
+ * against it would only prove the request is self-consistent, not that it targets this registry.
+ *
+ * Returns false rather than throwing, so an untrusted request can be passed in as-is.
+ */
+function verifyRegistrationRequest(request, expected) {
+    try {
+        if (request.version !== REQUEST_VERSION || request.schemeId !== SCHEME_ID)
+            return false;
+        // Neither field is covered by the signature, so both have to be pinned to the caller's own
+        // registry. Otherwise a signature made for another chain or contract replays here.
+        if (request.chainId !== expected.chainId)
+            return false;
+        if (request.verifyingContract.toLowerCase() !== expected.verifyingContract.toLowerCase())
+            return false;
+        // The contract types these as bytes32 and a 66-byte bytes. A request signed self-consistently
+        // over the wrong width verifies against itself but cannot be submitted.
+        const networkIdBytes = hexToBytes(request.networkId);
+        if (networkIdBytes.length !== NETWORK_ID_LENGTH)
+            return false;
+        if (hexToBytes(request.metaStealthAddress).length !== META_STEALTH_ADDRESS_LENGTH)
+            return false;
+        // Width alone admits 66 bytes the contract would store but no one could ever pay to.
+        if (!validateMetaStealthAddress(request.metaStealthAddress))
+            return false;
+        const signatureBytes = hexToBytes(request.signature);
+        if (signatureBytes.length !== SIGNATURE_LENGTH)
+            return false;
+        const rs = signatureBytes.slice(0, 64);
+        const recovery = signatureBytes[64] - 27;
+        if (recovery !== 0 && recovery !== 1)
+            return false;
+        const digest = registerIdentityDigest(expected, request.networkId, request.metaStealthAddress);
+        const signature = secp256k1.Signature.fromCompact(rs).addRecoveryBit(recovery);
+        // Signing uses `lowS` (EIP-2), so verification rejects high-S to agree with it.
+        if (signature.hasHighS())
+            return false;
+        const recoveredPublicKey = signature.recoverPublicKey(hexToBytes(digest)).toBytes(false);
+        // computeNetworkId is keccak256(X || Y); compare all 32 bytes. An address-style check over the
+        // low 20 would leave the top 12 unauthenticated and let one key claim 2^96 ids. The contract
+        // itself checks no signer at all.
+        return computeNetworkId(recoveredPublicKey).toLowerCase() === request.networkId.toLowerCase();
+    }
+    catch {
+        return false;
+    }
+}
+
+/**
+ * In-memory stand-in for the registry's read model and the two reverts on its register path,
+ * length then duplicate; updateIdentity/removeIdentity are not modelled. `tests/integration`
+ * asserts both reverts against the real contract and this fake side by side.
+ */
+class InMemoryIdentityRegistry {
+    constructor() {
+        this.identities = new Map();
+    }
+    registerIdentity(networkId, metaStealthAddress) {
+        const length = hexToBytes(metaStealthAddress).length;
+        if (length !== META_STEALTH_ADDRESS_LENGTH) {
+            throw new SubmissionFailedError(`InvalidMetaStealthAddressLength: expected ${META_STEALTH_ADDRESS_LENGTH} bytes, got ${length}`);
+        }
+        const key = networkId.toLowerCase();
+        if (this.identities.has(key)) {
+            throw new SubmissionFailedError(`AlreadyRegistered: ${networkId}`);
+        }
+        this.identities.set(key, metaStealthAddress);
+    }
+    async getIdentity(networkId) {
+        return this.identities.get(networkId.toLowerCase()) ?? null;
+    }
+}
+
+/**
+ * Stands in for an approved network member's server: checks the user's consent the way a real
+ * server must before writing, then writes. The Semaphore proof a real server builds before
+ * submitting on chain is implied by construction, not modeled here.
+ */
+class InMemoryMemberServer {
+    constructor(registry, domain) {
+        this.registry = registry;
+        this.domain = domain;
+    }
+    async submit(request) {
+        if (!verifyRegistrationRequest(request, this.domain)) {
+            throw new SubmissionFailedError("InvalidRegistrationRequest");
+        }
+        this.registry.registerIdentity(request.networkId, request.metaStealthAddress);
+        return { txHash: bytesToHex(keccak_256(hexToBytes(request.signature))) };
+    }
+}
+
+function onboard(deviceSecret) {
+    const keys = deriveKeys(deviceSecret);
+    const metaStealthAddress = metaStealthAddressFromKeys(keys);
+    return {
+        keys,
+        networkId: keys.networkId,
+        metaStealthAddress,
+        displayMetaStealthAddress: metaStealthAddressUri(metaStealthAddress)
+    };
+}
+/**
+ * IdentityRegistry stores the mapping as `bytes`, so its generated getter answers an unregistered
+ * networkId with empty bytes. A reader built straight onto viem or ethers therefore returns "0x"
+ * where this package's port requires null, and treating that as an entry would report success while
+ * never registering anything.
+ */
+function readExistingEntry(value, networkId) {
+    if (value === null || value === "0x")
+        return null;
+    const length = hexToBytes(value).length;
+    if (length !== META_STEALTH_ADDRESS_LENGTH) {
+        throw new UserClientError("INVALID_INPUT", `RegistryReader returned a ${length}-byte entry for ${networkId}; expected ${META_STEALTH_ADDRESS_LENGTH} bytes or null`);
+    }
+    return value;
+}
+async function register(params) {
+    const { keys, networkId, metaStealthAddress } = onboard(params.deviceSecret);
+    let existingRaw;
+    try {
+        existingRaw = await params.registry.getIdentity(networkId);
+    }
+    catch (error) {
+        throw new RegistryReadFailedError(`registry read failed for ${networkId}`, error);
+    }
+    const existing = readExistingEntry(existingRaw, networkId);
+    if (existing !== null) {
+        // A mismatch means this device's keys do not derive the address its networkId currently
+        // resolves to. Only a network member calling updateIdentity can change that entry.
+        return {
+            status: "alreadyRegistered",
+            networkId,
+            metaStealthAddress: existing,
+            derivedMetaStealthAddress: metaStealthAddress,
+            matchesDerived: existing.toLowerCase() === metaStealthAddress.toLowerCase()
+        };
+    }
+    const request = buildRegistrationRequest(keys, params.domain);
+    let receipt;
+    try {
+        receipt = await params.submitter.submit(request);
+    }
+    catch (error) {
+        if (error instanceof SubmissionFailedError)
+            throw error;
+        throw new SubmissionFailedError(`Registration submission failed for ${networkId}`, error);
+    }
+    return { status: "registered", networkId, metaStealthAddress, request, receipt };
+}
+
+/**
+ * Thrown by {@link createHttpRegistrationSubmitter}. `alreadyRegistered`
+ * carries the registry's current entry so a caller can re-run `register()`
+ * and land in its own `alreadyRegistered` branch once that's visible to
+ * `params.registry.getIdentity`.
+ */
+class HttpSubmissionError extends SubmissionFailedError {
+    constructor(message, init) {
+        super(message, init.cause);
+        this.name = "HttpSubmissionError";
+        this.status = init.status;
+        this.reason = init.reason;
+        this.serverCode = init.serverCode;
+        this.metaStealthAddress = init.metaStealthAddress;
+        this.matchesRequest = init.matchesRequest;
+    }
+}
+/** Parses `value` as a 32-byte `0x` hex tx hash, or `null` if it isn't one. */
+function parseTxHash(value) {
+    if (typeof value !== "string")
+        return null;
+    try {
+        return hexToBytes(value).length === TX_HASH_LENGTH ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * HTTP `RegistrationSubmitter` for `apps/issuer-service`'s `POST /v1/registrations`.
+ * Never logs or throws the request body or its signature — only the response
+ * status and, where sent, the server's own error code.
+ */
+function createHttpRegistrationSubmitter({ url, fetch: fetchImpl = fetch }) {
+    return {
+        async submit(request) {
+            let response;
+            try {
+                response = await fetchImpl(`${url}/v1/registrations`, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify(request)
+                });
+            }
+            catch (error) {
+                throw new HttpSubmissionError("Registration submission failed: network error", {
+                    reason: "network",
+                    cause: error
+                });
+            }
+            let body;
+            try {
+                body = await response.json();
+            }
+            catch (error) {
+                throw new HttpSubmissionError(`Registration submission returned ${response.status} with no JSON body`, {
+                    status: response.status,
+                    reason: "invalidResponse",
+                    cause: error
+                });
+            }
+            if (response.status === 201) {
+                const txHash = parseTxHash(body?.txHash);
+                if (txHash === null) {
+                    throw new HttpSubmissionError("Registration submission returned 201 with a malformed body", {
+                        status: 201,
+                        reason: "invalidResponse"
+                    });
+                }
+                return { txHash };
+            }
+            if (response.status === 200) {
+                const { metaStealthAddress, matchesRequest } = (body ?? {});
+                throw new HttpSubmissionError("Registration already exists for this networkId", {
+                    status: 200,
+                    reason: "alreadyRegistered",
+                    metaStealthAddress,
+                    matchesRequest
+                });
+            }
+            if (response.status === 400) {
+                throw new HttpSubmissionError("Registration submission was rejected", {
+                    status: 400,
+                    reason: "rejected"
+                });
+            }
+            if (response.status === 503) {
+                throw new HttpSubmissionError("Registration service is unavailable", {
+                    status: 503,
+                    reason: "unavailable",
+                    serverCode: body?.code
+                });
+            }
+            throw new HttpSubmissionError(`Registration submission returned unexpected status ${response.status}`, {
+                status: response.status,
+                reason: "invalidResponse"
+            });
+        }
+    };
+}
+
+export { DIGEST_LENGTH, EIP712_DOMAIN_TYPE, HttpSubmissionError, IDENTITY_REGISTRY_DOMAIN_NAME, IDENTITY_REGISTRY_DOMAIN_VERSION, InMemoryIdentityRegistry, InMemoryMemberServer, NETWORK_ID_LENGTH, REGISTER_IDENTITY_TYPE, REQUEST_VERSION, RegistryReadFailedError, SCHEME_ID, SIGNATURE_LENGTH, SubmissionFailedError, TX_HASH_LENGTH, UserClientError, buildRegistrationRequest, createHttpRegistrationSubmitter, identityRegistryDomainSeparator, metaStealthAddressFromKeys, onboard, register, registerIdentityDigest, registerIdentityStructHash, signRegisterIdentity, verifyRegistrationRequest };

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@coordination-network/user-client",
+  "version": "0.0.1",
+  "description": "Single-call onboarding and registration for the coordination network: derive device keys, encode the meta-stealth address, and register networkId -> metaStealthAddress on IdentityRegistry.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zk-kit/coordination-network.git",
+    "directory": "packages/user-client"
+  },
+  "homepage": "https://github.com/zk-kit/coordination-network/tree/main/packages/user-client",
+  "bugs": "https://github.com/zk-kit/coordination-network/issues",
+  "sideEffects": false,
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "types/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rimraf dist types && rollup -c rollup.config.mjs"
+  },
+  "dependencies": {
+    "@coordination-network/identity": "^0.0.1",
+    "@noble/curves": "^1.9.7",
+    "@noble/hashes": "^1.8.0"
+  },
+  "devDependencies": {
+    "@coordination-network/network-member-client": "^0.0.1",
+    "@coordination-network/network-member-proof": "^0.0.1",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@semaphore-protocol/group": "4.14.3",
+    "@semaphore-protocol/identity": "4.14.3",
+    "rimraf": "^6.1.3",
+    "rollup": "^4.62.2",
+    "rollup-plugin-cleanup": "^3.2.1",
+    "rollup-plugin-dts": "^6.4.1",
+    "tslib": "^2.8.0",
+    "typescript": "^6.0.3",
+    "viem": "^2.55.11"
+  }
+}

package/src/bytes.ts

@@ -0,0 +1,52 @@
+import {
+    hexToBytes as nobleHexToBytes,
+    bytesToHex as nobleBytesToHex,
+    concatBytes as nobleConcatBytes
+} from "@noble/hashes/utils"
+import { Hex } from "./types"
+import { UserClientError } from "./errors"
+
+/** Parses a 0x-prefixed hex string into bytes. Throws on missing prefix, odd length, or non-hex chars. */
+export function hexToBytes(hex: Hex): Uint8Array {
+    if (typeof hex !== "string" || !hex.startsWith("0x")) {
+        throw new UserClientError("INVALID_INPUT", `Expected a 0x-prefixed hex string, got ${typeof hex}`)
+    }
+    const body = hex.slice(2)
+    if (body.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(body)) {
+        throw new UserClientError("INVALID_INPUT", `Malformed hex string of length ${body.length}`)
+    }
+    return nobleHexToBytes(body)
+}
+
+export function bytesToHex(bytes: Uint8Array): Hex {
+    return `0x${nobleBytesToHex(bytes)}` as Hex
+}
+
+export function concatBytes(...arrays: Uint8Array[]): Uint8Array {
+    return nobleConcatBytes(...arrays)
+}
+
+/** Big-endian 32-byte word encoding of a non-negative safe-integer uint256, as abi.encode would produce. */
+export function numberToWord(value: number): Uint8Array {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new UserClientError("INVALID_INPUT", `Expected a non-negative safe integer, got ${typeof value} ${value}`)
+    }
+    const word = new Uint8Array(32)
+    let remaining = BigInt(value)
+    for (let i = 31; i >= 0 && remaining > 0n; i -= 1) {
+        word[i] = Number(remaining & 0xffn)
+        remaining >>= 8n
+    }
+    return word
+}
+
+/** Left-pads a 20-byte address into a 32-byte word, as abi.encode would produce. */
+export function addressToWord(address: Hex): Uint8Array {
+    const addressBytes = hexToBytes(address)
+    if (addressBytes.length !== 20) {
+        throw new UserClientError("INVALID_INPUT", `Expected a 20-byte address, got ${addressBytes.length} bytes`)
+    }
+    const word = new Uint8Array(32)
+    word.set(addressBytes, 12)
+    return word
+}

package/src/constants.ts

@@ -0,0 +1,17 @@
+/** ERC-6538 scheme 1 (secp256k1 stealth addresses), the schemeId field of the consent struct. */
+export const SCHEME_ID = 1 as const
+/** networkId is a bytes32 on chain, and abi.encode splices it in as one word. */
+export const NETWORK_ID_LENGTH = 32
+/** r || s || v, the 65-byte Ethereum signature layout. */
+export const SIGNATURE_LENGTH = 65
+/** keccak256 output, the only thing this package will sign. */
+export const DIGEST_LENGTH = 32
+/** Ethereum transaction hash, as HttpSubmissionError's 201 branch expects it. */
+export const TX_HASH_LENGTH = 32
+/** Wire-format version of RegistrationRequest. */
+export const REQUEST_VERSION = "v1" as const
+export const IDENTITY_REGISTRY_DOMAIN_NAME = "IdentityRegistry"
+export const IDENTITY_REGISTRY_DOMAIN_VERSION = "1"
+/** Signed by the user as consent to register; the member server verifies it, the contract never reads it. */
+export const REGISTER_IDENTITY_TYPE = "RegisterIdentity(bytes32 networkId,uint256 schemeId,bytes metaStealthAddress)"
+export const EIP712_DOMAIN_TYPE = "EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)"

package/src/eip712.ts

@@ -0,0 +1,57 @@
+import { keccak_256 } from "@noble/hashes/sha3"
+import { utf8ToBytes } from "@noble/hashes/utils"
+import { ChainDomain, Hex } from "./types"
+import { UserClientError } from "./errors"
+import { hexToBytes, bytesToHex, concatBytes, numberToWord, addressToWord } from "./bytes"
+import {
+    REGISTER_IDENTITY_TYPE,
+    EIP712_DOMAIN_TYPE,
+    IDENTITY_REGISTRY_DOMAIN_NAME,
+    IDENTITY_REGISTRY_DOMAIN_VERSION,
+    NETWORK_ID_LENGTH,
+    SCHEME_ID
+} from "./constants"
+
+const EIP712_DOMAIN_TYPEHASH = keccak_256(utf8ToBytes(EIP712_DOMAIN_TYPE))
+const REGISTER_IDENTITY_TYPEHASH = keccak_256(utf8ToBytes(REGISTER_IDENTITY_TYPE))
+
+/** Every input is already a 32-byte word, so concatenating them is what abi.encode would emit. */
+function hashEncodedWords(...words: Uint8Array[]): Uint8Array {
+    return keccak_256(concatBytes(...words))
+}
+
+export function identityRegistryDomainSeparator(domain: ChainDomain): Hex {
+    const nameHash = keccak_256(utf8ToBytes(IDENTITY_REGISTRY_DOMAIN_NAME))
+    const versionHash = keccak_256(utf8ToBytes(IDENTITY_REGISTRY_DOMAIN_VERSION))
+    return bytesToHex(
+        hashEncodedWords(
+            EIP712_DOMAIN_TYPEHASH,
+            nameHash,
+            versionHash,
+            numberToWord(domain.chainId),
+            addressToWord(domain.verifyingContract)
+        )
+    )
+}
+
+export function registerIdentityStructHash(networkId: Hex, metaStealthAddress: Hex): Hex {
+    const networkIdWord = hexToBytes(networkId)
+    if (networkIdWord.length !== NETWORK_ID_LENGTH) {
+        throw new UserClientError(
+            "INVALID_INPUT",
+            `Expected a ${NETWORK_ID_LENGTH}-byte networkId, got ${networkIdWord.length} bytes`
+        )
+    }
+    const metaHash = keccak_256(hexToBytes(metaStealthAddress))
+    return bytesToHex(hashEncodedWords(REGISTER_IDENTITY_TYPEHASH, networkIdWord, numberToWord(SCHEME_ID), metaHash))
+}
+
+/**
+ * The digest the user signs as consent to register this meta-stealth address at this registry on
+ * this chain. The member server verifies it before submitting; the contract never reads it.
+ */
+export function registerIdentityDigest(domain: ChainDomain, networkId: Hex, metaStealthAddress: Hex): Hex {
+    const domainSeparator = hexToBytes(identityRegistryDomainSeparator(domain))
+    const structHash = hexToBytes(registerIdentityStructHash(networkId, metaStealthAddress))
+    return bytesToHex(keccak_256(concatBytes(Uint8Array.from([0x19, 0x01]), domainSeparator, structHash)))
+}

package/src/errors.ts

@@ -0,0 +1,40 @@
+export type UserClientErrorCode = "INVALID_INPUT" | "SUBMISSION_FAILED" | "REGISTRY_READ_FAILED"
+
+/** Base error class for all errors thrown by this package, discriminated by `code`. */
+export class UserClientError extends Error {
+    readonly code: UserClientErrorCode
+    constructor(code: UserClientErrorCode, message: string) {
+        super(message)
+        this.name = "UserClientError"
+        this.code = code
+    }
+}
+
+export class SubmissionFailedError extends UserClientError {
+    // `declare` emits no field: at ES2022 one would be created enumerable, defeating defineProperty.
+    declare readonly cause?: unknown
+
+    constructor(message: string, cause?: unknown) {
+        super("SUBMISSION_FAILED", message)
+        this.name = "SubmissionFailedError"
+        if (cause !== undefined) {
+            // Non-enumerable, matching the standard Error.cause. Provider errors hold circular
+            // transport graphs, so an enumerable copy makes JSON.stringify throw inside a
+            // caller's error handler and drags the provider's URL into its logs.
+            Object.defineProperty(this, "cause", { value: cause, writable: true, configurable: true })
+        }
+    }
+}
+
+export class RegistryReadFailedError extends UserClientError {
+    // See SubmissionFailedError's constructor for why cause is declared and non-enumerable.
+    declare readonly cause?: unknown
+
+    constructor(message: string, cause?: unknown) {
+        super("REGISTRY_READ_FAILED", message)
+        this.name = "RegistryReadFailedError"
+        if (cause !== undefined) {
+            Object.defineProperty(this, "cause", { value: cause, writable: true, configurable: true })
+        }
+    }
+}