opacity-issuer-core 0.2.1

package/dist/documents/index.d.cts

@@ -0,0 +1,1370 @@
+import { Hex, Address } from 'viem';
+import { C as ClockOptions, b as BuildDocumentAcceptanceTypedDataParams, B as BuildAttestDocumentTransactionParams, T as TransactionRequest } from '../types-B4Yi7WA4.cjs';
+export { A as AttestationErrorCode, a as AttestationSession, D as DocumentAttestorContext } from '../types-B4Yi7WA4.cjs';
+
+/**
+ * Minimal ABI for `DocumentAttestor`, hand-written rather than copied from a Foundry artifact.
+ *
+ * The contracts repo's `release-abis.yml` only syncs `AllowlistRegistry.json` downstream, so there
+ * is no artifact pipeline to consume here; a hand-written `as const` array also keeps viem's type
+ * inference sharp and the published bundle small.
+ *
+ * It covers the write path this SDK builds (`attestDocument`), the reads worth verifying a
+ * deployment against, and the errors reachable from `attestDocument` — including the two from
+ * `AllowlistRegistry` and `EnforcedPause`, which bubble up through `enableTraitAsWriter` and are
+ * the likeliest failures in practice (writer role never granted, trait not writer-enableable,
+ * registry paused). Pass this ABI to viem's revert decoding to get a named error instead of a raw
+ * selector.
+ *
+ * Owner-only functions (`setServerSigner`, the `Ownable2Step` surface) are deliberately absent —
+ * they are outside this module's scope.
+ */
+declare const documentAttestorAbi: readonly [{
+    readonly type: "function";
+    readonly name: "attestDocument";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "wallet";
+        readonly type: "address";
+    }, {
+        readonly name: "traitId";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "docHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "issuedAt";
+        readonly type: "uint256";
+    }, {
+        readonly name: "deadline";
+        readonly type: "uint256";
+    }, {
+        readonly name: "serverSignature";
+        readonly type: "bytes";
+    }, {
+        readonly name: "userSignature";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "serverSigner";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "usedNonces";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "retiredSigners";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "signer";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "allowlistRegistry";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "MAX_ATTESTATION_LIFETIME";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "DOCUMENT_ACCEPTANCE_TYPEHASH";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "bytes32";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "ATTESTATION_AUTHORIZATION_TYPEHASH";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "bytes32";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "eip712Domain";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "fields";
+        readonly type: "bytes1";
+    }, {
+        readonly name: "name";
+        readonly type: "string";
+    }, {
+        readonly name: "version";
+        readonly type: "string";
+    }, {
+        readonly name: "chainId";
+        readonly type: "uint256";
+    }, {
+        readonly name: "verifyingContract";
+        readonly type: "address";
+    }, {
+        readonly name: "salt";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "extensions";
+        readonly type: "uint256[]";
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "DocumentAttested";
+    readonly inputs: readonly [{
+        readonly name: "userId";
+        readonly type: "bytes32";
+        readonly indexed: true;
+    }, {
+        readonly name: "wallet";
+        readonly type: "address";
+        readonly indexed: true;
+    }, {
+        readonly name: "traitId";
+        readonly type: "bytes32";
+        readonly indexed: true;
+    }, {
+        readonly name: "docHash";
+        readonly type: "bytes32";
+        readonly indexed: false;
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+        readonly indexed: false;
+    }];
+    readonly anonymous: false;
+}, {
+    readonly type: "error";
+    readonly name: "ZeroAddress";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "InvalidTraitId";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "InvalidDocHash";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "NonceAlreadyUsed";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "AttestationExpired";
+    readonly inputs: readonly [{
+        readonly name: "deadline";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "error";
+    readonly name: "AttestationDeadlineTooFar";
+    readonly inputs: readonly [{
+        readonly name: "deadline";
+        readonly type: "uint256";
+    }, {
+        readonly name: "maxAllowed";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "error";
+    readonly name: "AttestationIssuedInFuture";
+    readonly inputs: readonly [{
+        readonly name: "issuedAt";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "error";
+    readonly name: "WalletNotOnboarded";
+    readonly inputs: readonly [{
+        readonly name: "wallet";
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "error";
+    readonly name: "InvalidServerSignature";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "SignerRetired";
+    readonly inputs: readonly [{
+        readonly name: "signer";
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "error";
+    readonly name: "InvalidUserSignature";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "ECDSAInvalidSignature";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "ECDSAInvalidSignatureLength";
+    readonly inputs: readonly [{
+        readonly name: "length";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "error";
+    readonly name: "ECDSAInvalidSignatureS";
+    readonly inputs: readonly [{
+        readonly name: "s";
+        readonly type: "bytes32";
+    }];
+}, {
+    readonly type: "error";
+    readonly name: "NotTraitWriter";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "TraitNotWriterEnableable";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "EnforcedPause";
+    readonly inputs: readonly [];
+}];
+
+/**
+ * EIP-712 domain `name` and `version`, from `EIP712("DocumentAttestor", "1")` in
+ * `DocumentAttestor.sol`. The domain has no `salt` — OpenZeppelin's `EIP712` uses
+ * `EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)`.
+ */
+declare const DOCUMENT_ATTESTOR_DOMAIN_NAME = "DocumentAttestor";
+declare const DOCUMENT_ATTESTOR_DOMAIN_VERSION = "1";
+/**
+ * The payload the investor's wallet signs.
+ *
+ * It deliberately binds neither `wallet` nor `traitId`: the trait is an internal mapping and the
+ * prompt should show only what the human is agreeing to, while the binding to a wallet comes from
+ * ECDSA recovery (or, for ERC-1271, from the server's own signature). Cross-deployment and
+ * cross-chain replay are stopped by the domain's `chainId` + `verifyingContract`.
+ *
+ * Field order is consensus-critical — it is part of the type hash.
+ */
+declare const DOCUMENT_ACCEPTANCE_TYPES: {
+    readonly DocumentAcceptance: readonly [{
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "docHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "deadline";
+        readonly type: "uint256";
+    }];
+};
+declare const DOCUMENT_ACCEPTANCE_PRIMARY_TYPE = "DocumentAcceptance";
+/**
+ * The EIP-712 domain type, needed only by `toEip712JsonPayload`: raw `eth_signTypedData_v4`
+ * requires `EIP712Domain` to be present in `types`, whereas viem derives it and ethers v6 throws
+ * if you supply it.
+ */
+declare const EIP712_DOMAIN_TYPE: readonly [{
+    readonly name: "name";
+    readonly type: "string";
+}, {
+    readonly name: "version";
+    readonly type: "string";
+}, {
+    readonly name: "chainId";
+    readonly type: "uint256";
+}, {
+    readonly name: "verifyingContract";
+    readonly type: "address";
+}];
+/**
+ * `keccak256("DocumentAcceptance(bytes32 nonce,bytes32 docHash,uint256 deadline)")`.
+ *
+ * Not used to build the payload (viem derives it from {@link DOCUMENT_ACCEPTANCE_TYPES}); exported
+ * so a consumer can assert it against the contract's `DOCUMENT_ACCEPTANCE_TYPEHASH()` getter.
+ */
+declare const DOCUMENT_ACCEPTANCE_TYPEHASH: Hex;
+/**
+ * Mirrors `DocumentAttestor.MAX_ATTESTATION_LIFETIME` (30 days).
+ *
+ * Duplicated off-chain so `deadline > issuedAt + MAX_ATTESTATION_LIFETIME` can be caught before the
+ * investor is prompted, rather than at redemption. It is a `constant` on a non-upgradeable contract,
+ * so it cannot drift for a given deployment — but a successor deployment could choose a different
+ * value, which is why `MAX_ATTESTATION_LIFETIME` is kept in `documentAttestorAbi` for
+ * consumers that want to read it back.
+ */
+declare const MAX_ATTESTATION_LIFETIME_SECONDS = 2592000n;
+/** Length in bytes of the ECDSA signature `ECDSA.recover` accepts — it rejects every other length. */
+declare const ECDSA_SIGNATURE_BYTES = 65;
+
+/**
+ * Derives a trait id from its canonical name: `keccak256(utf8(name))`.
+ *
+ * Matches the convention the contracts use verbatim — `keccak256("doc.offering7.subscription.v1")`
+ * in Solidity is `documentTraitId('doc.offering7.subscription.v1')` here.
+ *
+ * The document VERSION is part of the name, deliberately: amendments roll the id forward, so a
+ * policy that requires `…v2` makes every `…v1` attestation inert without touching a contract.
+ *
+ * The resulting id must be writer-enableable on the registry
+ * (`AllowlistRegistry.setWriterEnableableTrait`) or `attestDocument` reverts
+ * `TraitNotWriterEnableable`.
+ */
+declare function documentTraitId(name: string): Hex;
+/**
+ * Hashes a document to the `docHash` an attestation binds to.
+ *
+ * Must be the EXECUTED document — the post-signature artifact — not the blank template. Pass the
+ * raw bytes (e.g. a `Uint8Array` of the PDF); a `string` is hashed as UTF-8.
+ */
+declare function hashDocument(content: Uint8Array | string): Hex;
+
+/**
+ * Asserts that the bytes the app rendered still hash to the `docHash` the investor is about to
+ * sign.
+ *
+ * **This is the single most security-relevant check the client half performs**, and the only thing
+ * tying a signature to real paperwork. The 2-of-2 design defends against a compromised server
+ * acting alone and against an investor acting alone; it does nothing about a client that signs
+ * whatever `docHash` arrives over the wire, because the attestor never sees the document at all —
+ * only its hash.
+ *
+ * Since the client is what produced and submitted that hash in the first place, a mismatch never
+ * means "the server sent the wrong document" — the server has no document to send. It means one of:
+ *
+ * - the session echoed back a different `docHash` than the one posted to `POST /attestations`;
+ * - the bytes changed between being hashed and being rendered;
+ * - the wrong artifact is in hand — a blank template, or a re-encoded copy of the executed one.
+ *
+ * Call it before `buildDocumentAcceptanceTypedData` and refuse to raise the wallet prompt if it
+ * throws. Pass the EXECUTED artifact — the same post-signature bytes that were hashed for
+ * `POST /attestations` — not the blank template, and not a re-rendered or re-encoded copy of it.
+ * Hashing is byte-exact: a PDF that has been through a viewer's save path will not match even
+ * though it looks identical.
+ *
+ * The comparison is case-insensitive. `hashDocument` returns lower-case hex, but a `docHash` that
+ * arrived inside a JSON session payload may be upper- or mixed-case, and rejecting a valid document
+ * over hex casing would be a silent, extremely confusing failure. Constant-time comparison is not
+ * warranted: both values are public, and anyone in a position to substitute the hash already knows
+ * the one they substituted.
+ *
+ * @throws {OpacityAttestationError} `DocHashMismatch` when the content hashes to something other
+ *   than `expectedDocHash`; `InvalidDocHash` / `MalformedInput` when `expectedDocHash` is zero or
+ *   not 32 bytes of hex, or when `content` is empty or of the wrong type.
+ */
+declare function assertDocumentMatchesHash(content: Uint8Array | string, expectedDocHash: Hex): void;
+/**
+ * The parts of a `POST /attestations` response this module reads.
+ *
+ * Declared structurally, so the full response type — or a raw `JSON.parse` result — satisfies it
+ * without conversion, and so this module does not have to move every time the rest of the response
+ * grows a field.
+ */
+interface AttestationSessionResponseLike {
+    /**
+     * Top-level echo of the hash the client submitted. Optional here only for tolerance; the locked
+     * schema always sends it, and it is cross-checked against the signed copy when present.
+     */
+    docHash?: Hex | undefined;
+    /** Session expiry, unix seconds. A NUMBER on the locked wire; a bigint or decimal string is fine. */
+    deadline: number | bigint | string;
+    /** The EIP-712 payload the wallet is about to sign. Only `message` is read. */
+    typedData: {
+        message: {
+            /** The copy of the hash that is actually signed — this is the one that gets checked. */
+            docHash: Hex;
+            /** Decimal STRING on the wire, since `eth_signTypedData_v4` wants `uint256` as a string. */
+            deadline?: number | bigint | string | undefined;
+        };
+    };
+}
+/** Shared by both shapes {@link verifyAttestationSession} accepts. */
+interface VerifyAttestationSessionBase extends ClockOptions {
+    /** The document bytes the app rendered to the investor. A `string` is hashed as UTF-8. */
+    content: Uint8Array | string;
+    /**
+     * Optional, and normally absent: the client-facing session deliberately does not carry
+     * `issuedAt` — the investor does not sign it. Supply it if you have it server-side and the
+     * 30-day lifetime cap is checked too.
+     */
+    issuedAt?: bigint | number | string;
+}
+/** Pass the session's fields directly, e.g. when they were carried through your own types. */
+interface VerifyAttestationSessionFields extends VerifyAttestationSessionBase {
+    /** `docHash` exactly as the session delivered it. Compared case-insensitively. */
+    docHash: Hex;
+    /** Session expiry, unix seconds, in any of the forms the wire uses. */
+    deadline: bigint | number | string;
+}
+/** Hand over the `POST /attestations` response itself and let the SDK read it. */
+interface VerifyAttestationSessionResponseParams extends VerifyAttestationSessionBase {
+    /** The session response as received. `docHash` is read from `typedData.message`. */
+    session: AttestationSessionResponseLike;
+}
+/**
+ * What {@link verifyAttestationSession} needs: the rendered bytes, plus either the session response
+ * itself or the two fields read out of it.
+ */
+type VerifyAttestationSessionParams = VerifyAttestationSessionFields | VerifyAttestationSessionResponseParams;
+/**
+ * The one pre-flight call a UI should make before prompting the wallet.
+ *
+ * Combines the two questions worth asking while the investor is still looking at the document: is
+ * this still the document the session commits to ({@link assertDocumentMatchesHash}), and is the
+ * session still signable (`assertSessionWindow`, so the lifetime and expiry rules live in exactly
+ * one place)?
+ *
+ * Hand it the session response as it arrived, and the fields are read from the copies that are
+ * actually signed:
+ *
+ * ```ts
+ * const session = await client.http.post('/attestations', { wallet, docHash }); // 201 body
+ *
+ * verifyAttestationSession({
+ *   content: pdfBytes, // the same executed bytes that were hashed into `docHash` above
+ *   session,
+ *   now: BigInt(Math.floor(Date.now() / 1000)), // optional; also checks expiry
+ * });
+ *
+ * const signature = await walletClient.signTypedData({
+ *   account,
+ *   ...toViemTypedData(session.typedData, { expectedAttestor }),
+ * });
+ * ```
+ *
+ * viem would take `session.typedData` unchanged, but `toViemTypedData` is the shape to reach for:
+ * it validates `primaryType`, the `DocumentAcceptance` field list and its ORDER, and the domain,
+ * and `expectedAttestor` / `expectedChainId` pin the prompt to the deployment this integration
+ * trusts. This function checks the document; that one checks the payload built around it.
+ *
+ * The fields may also be passed directly — `{ content, docHash, deadline }` — when they have been
+ * carried through an app's own types. Either way `docHash` comes from `typedData.message` in
+ * preference to the top-level echo, since that is the copy the wallet signs, and `deadline` is
+ * coerced from the top-level number (a decimal string or a `bigint` works too).
+ *
+ * The document check runs first on purpose. When a session is both expired and mismatched, the
+ * mismatch is the finding that matters: an expiry is a benign retry, whereas a hash that no longer
+ * matches the bytes on screen means the backend is not committing to the document being signed,
+ * and no amount of re-issuing sessions will fix that.
+ *
+ * ### Safes, ERC-1271, and the session TTL
+ *
+ * This is where an expired session surfaces, so it is also where too short a TTL shows up. Sessions
+ * default to a 3600-second TTL (env-tunable up to the contract's 30-day `MAX_ATTESTATION_LIFETIME`
+ * cap). An ERC-1271 signer — a Safe — produces no signature until enough owners have confirmed, and
+ * that ceremony routinely outlasts an hour. The `deadline` must outlive it: issuers whose investors
+ * sign from Safes should have the TTL raised, or the session lapses mid-ceremony and the investor
+ * is asked to start over. An `AttestationExpired` from this function on a Safe flow is a TTL
+ * configuration finding, not an investor mistake.
+ *
+ * What this does *not* do: verify the server's half of the authorization. That signature is never
+ * given to the client — checking it is the attestor's job, on-chain.
+ *
+ * The clock checks stay opt-in — omit `now` and a skewed device clock cannot refuse a session the
+ * chain would have accepted. Pass `BigInt(Math.floor(Date.now() / 1000))` to enable them.
+ *
+ * @throws {OpacityAttestationError} See {@link assertDocumentMatchesHash}, plus
+ *   `AttestationExpired`, `AttestationDeadlineTooFar`, `AttestationIssuedInFuture`, and
+ *   `MalformedInput` for a session whose `deadline` copies disagree or cannot be read.
+ */
+declare function verifyAttestationSession(params: VerifyAttestationSessionParams): void;
+
+/** The EIP-712 domain of a `DocumentAttestor` deployment. No `salt` — see `constants.ts`. */
+interface DocumentAttestorDomain {
+    name: typeof DOCUMENT_ATTESTOR_DOMAIN_NAME;
+    version: typeof DOCUMENT_ATTESTOR_DOMAIN_VERSION;
+    chainId: number;
+    verifyingContract: Address;
+}
+/** What the investor's wallet is asked to sign. */
+interface DocumentAcceptanceMessage {
+    nonce: Hex;
+    docHash: Hex;
+    deadline: bigint;
+}
+/**
+ * A viem/wagmi-native EIP-712 payload.
+ *
+ * `types` deliberately omits `EIP712Domain`: viem derives the domain type from the `domain` object
+ * when the entry is absent, and ethers v6 throws if it is present. Omitting it is only safe
+ * *because* those two derive it — a raw `eth_signTypedData_v4` provider does not, so use
+ * {@link toEip712JsonPayload} / {@link toEip712Json} for that path. Never hand this shape to
+ * `eth_signTypedData_v4` directly; see {@link toEip712JsonPayload} for what silently goes wrong.
+ */
+interface DocumentAcceptanceTypedData {
+    domain: DocumentAttestorDomain;
+    types: typeof DOCUMENT_ACCEPTANCE_TYPES;
+    primaryType: typeof DOCUMENT_ACCEPTANCE_PRIMARY_TYPE;
+    message: DocumentAcceptanceMessage;
+}
+/**
+ * Builds the EIP-712 payload the investor's wallet signs to accept a document.
+ *
+ * This is a signature prompt, not a transaction: it costs no gas and broadcasts nothing. It is
+ * also the investor's *only* wallet interaction — the resulting signature is posted back to the
+ * backend, which pairs it with the server's half and relays `buildAttestDocumentTransaction` from
+ * a gas-sponsor key. The investor never sends a transaction and never needs to hold gas.
+ *
+ * The returned object is what viem and wagmi want as-is:
+ *
+ * ```ts
+ * const typedData = buildDocumentAcceptanceTypedData({
+ *   attestorAddress, chainId, nonce, docHash, deadline, issuedAt,
+ * });
+ *
+ * const signature = await walletClient.signTypedData({ account, ...typedData }); // viem
+ * const signature = await signTypedDataAsync(typedData);                         // wagmi
+ * ```
+ *
+ * For other stacks, pass it through {@link toEthersTypedData} or {@link toEip712JsonPayload}.
+ *
+ * @throws {import('../errors.js').OpacityAttestationError} when a parameter would produce a
+ *   signature the attestor is guaranteed to reject.
+ */
+declare function buildDocumentAcceptanceTypedData(params: BuildDocumentAcceptanceTypedDataParams): DocumentAcceptanceTypedData;
+/**
+ * The EIP-712 digest the wallet actually signs.
+ *
+ * Useful for logging or for checking a returned signature offline. Note that an ERC-1271 wallet's
+ * signature is not recoverable to an address, so digest comparison is not a substitute for the
+ * on-chain `SignatureChecker` result.
+ */
+declare function hashDocumentAcceptance(typedData: DocumentAcceptanceTypedData): Hex;
+/** ethers v6 `signer.signTypedData(domain, types, value)` takes three positional arguments. */
+interface EthersTypedData {
+    domain: DocumentAttestorDomain;
+    /**
+     * A MUTABLE copy of {@link DOCUMENT_ACCEPTANCE_TYPES}, not the readonly constant itself:
+     * ethers v6 types `signTypedData`'s second argument as `Record<string, TypedDataField[]>`
+     * (mutable arrays), so the SDK's deeply-readonly `as const` shape fails TS2345 when passed
+     * directly. Structurally typed rather than importing ethers' `TypedDataField` — ethers is not
+     * a dependency of this package, and its types must not leak into the published declarations.
+     */
+    types: {
+        DocumentAcceptance: {
+            name: string;
+            type: string;
+        }[];
+    };
+    value: DocumentAcceptanceMessage;
+}
+/**
+ * Reshapes the payload for ethers v6.
+ *
+ * ```ts
+ * const { domain, types, value } = toEthersTypedData(typedData);
+ * const signature = await signer.signTypedData(domain, types, value);
+ * ```
+ *
+ * `types` still omits `EIP712Domain` — ethers infers the domain from its first argument and throws
+ * if the type is also declared.
+ */
+declare function toEthersTypedData(typedData: DocumentAcceptanceTypedData): EthersTypedData;
+/** A JSON-safe `eth_signTypedData_v4` payload: no bigints, `EIP712Domain` declared. */
+interface Eip712JsonPayload {
+    types: Record<string, ReadonlyArray<{
+        readonly name: string;
+        readonly type: string;
+    }>>;
+    primaryType: string;
+    domain: {
+        name: string;
+        version: string;
+        chainId: number;
+        verifyingContract: Address;
+    };
+    /** `deadline` is a decimal string, not a bigint — JSON cannot carry one. */
+    message: {
+        nonce: Hex;
+        docHash: Hex;
+        deadline: string;
+    };
+}
+/**
+ * Reshapes the payload for a raw EIP-1193 provider.
+ *
+ * This is the lowest common denominator every wallet connection service bottoms out at — MetaMask,
+ * WalletConnect, Coinbase Wallet, Privy, Dynamic, and the Safe Apps SDK all accept it:
+ *
+ * ```ts
+ * const signature = await provider.request({
+ *   method: 'eth_signTypedData_v4',
+ *   params: [account, toEip712Json(typedData)],
+ * });
+ * ```
+ *
+ * Two differences from the viem shape are required by the JSON-RPC method, not stylistic:
+ * `EIP712Domain` must be declared in `types`, and `uint256` values are decimal strings because JSON
+ * cannot carry a bigint.
+ *
+ * **Declaring `EIP712Domain` is load-bearing, and its absence fails SILENTLY.** MetaMask's
+ * `eth-sig-util` sanitises the payload with `{ EIP712Domain: [], ...types }`, so a payload that
+ * omits the entry does not error — it hashes the domain as `keccak256("EIP712Domain()")`, a type
+ * with NO fields, and the digest moves:
+ *
+ * ```text
+ * EIP712Domain declared     0x91feb0709c4ebdff9ccc57b12b26c50936eae7973f67c6d23780fcfdbda3f410  ✓
+ * EIP712Domain defaulted [] 0x82ada7044278f3b529058b2dac44bb987f078c23b15195e1dca77110f0c91691  ✗
+ * ```
+ *
+ * The wallet then returns a perfectly well-formed signature over the WRONG digest, which the
+ * backend rejects at its simulate step with `InvalidUserSignature` — far from the cause, and
+ * indistinguishable to the investor from "the wallet is broken". Declaring the type does not touch
+ * the `DocumentAcceptance` struct hash; it only makes the DOMAIN hash correct. So this is strictly
+ * a fix, never a behaviour change, and the `EIP712Domain` entry must not be removed from this
+ * function on the theory that the wallet will derive it.
+ */
+declare function toEip712JsonPayload(typedData: DocumentAcceptanceTypedData): Eip712JsonPayload;
+/**
+ * {@link toEip712JsonPayload}, serialised — the second `eth_signTypedData_v4` parameter.
+ *
+ * A backend-issued payload reaches this through `toEip712Json(toViemTypedData(session.typedData))`:
+ * `toViemTypedData` validates and normalises the server's JSON, and this re-serialises it with
+ * `EIP712Domain` declared.
+ *
+ * That round trip is optional on this path. mobile-api already declares `EIP712Domain` and already
+ * sends `deadline` as a decimal string, so `session.typedData` is a correct
+ * `eth_signTypedData_v4` payload exactly as it arrives — nothing is corrupted by sending it
+ * directly. Going through `toViemTypedData` buys validation (`primaryType`, the field list and its
+ * ORDER, the domain) and `expectedAttestor` / `expectedChainId` pinning, and it re-declares
+ * `EIP712Domain` from this SDK's own constant rather than trusting the wire's copy. Prefer it, but
+ * do not treat the direct route as broken.
+ */
+declare function toEip712Json(typedData: DocumentAcceptanceTypedData): string;
+
+/** `attestDocument` arguments, in the contract's positional order. */
+type AttestDocumentArgs = readonly [
+    wallet: Address,
+    traitId: Hex,
+    docHash: Hex,
+    nonce: Hex,
+    issuedAt: bigint,
+    deadline: bigint,
+    serverSignature: Hex,
+    userSignature: Hex
+];
+/**
+ * Builds the `attestDocument` transaction that redeems a signed session on-chain.
+ *
+ * This is the relay half of the flow, so its consumer is the backend, not the browser. The
+ * investor's entire involvement is the off-chain signature from
+ * {@link import('./typed-data.js').buildDocumentAcceptanceTypedData} — one wallet prompt, no
+ * transaction, no gas. The relayer pairs that signature with the server's half and broadcasts this
+ * call from a gas-sponsor key.
+ *
+ * The call is permissionless — `msg.sender` is never trusted and never recorded — so `from` is
+ * optional, and when supplied it names the sponsor account paying for gas. The descriptor works
+ * as-is with viem, wagmi and ethers v6:
+ *
+ * ```ts
+ * const tx = buildAttestDocumentTransaction({ ... });
+ *
+ * await walletClient.sendTransaction({ account, ...tx });  // viem
+ * sendTransaction(tx);                                     // wagmi
+ * await signer.sendTransaction(tx);                        // ethers v6
+ * ```
+ *
+ * See {@link toWriteContractRequest} for wagmi's `useWriteContract`, and
+ * {@link toJsonRpcTransaction} for a raw EIP-1193 provider.
+ *
+ * @throws {import('../errors.js').OpacityAttestationError} when a parameter would produce a
+ *   transaction the attestor is guaranteed to revert.
+ */
+declare function buildAttestDocumentTransaction(params: BuildAttestDocumentTransactionParams): TransactionRequest;
+/** The ABI-level form of the same call, for viem `writeContract` / wagmi `useWriteContract`. */
+interface WriteContractRequest {
+    address: Address;
+    abi: typeof documentAttestorAbi;
+    functionName: 'attestDocument';
+    args: AttestDocumentArgs;
+    chainId: number;
+}
+/**
+ * The same call expressed as contract arguments rather than calldata.
+ *
+ * Preferred by wagmi users, and it gives viem the ABI it needs to decode a revert into a named
+ * error (`NotTraitWriter`, `NonceAlreadyUsed`, …) instead of a bare selector.
+ *
+ * ```ts
+ * writeContract(toWriteContractRequest(params));
+ * ```
+ */
+declare function toWriteContractRequest(params: BuildAttestDocumentTransactionParams): WriteContractRequest;
+/** An `eth_sendTransaction` parameter object — every numeric field hex-encoded. */
+interface JsonRpcTransaction {
+    from: Address;
+    to: Address;
+    data: Hex;
+    value: Hex;
+    chainId: Hex;
+}
+/**
+ * Reshapes the descriptor for a raw EIP-1193 provider.
+ *
+ * `eth_sendTransaction` demands a mandatory `from` and hex-quantity encoding; the chain-agnostic
+ * descriptor has neither (its own `from` is optional and its quantities are bigints), so the
+ * sending account is passed explicitly here — under relay, that is the gas sponsor:
+ *
+ * ```ts
+ * const hash = await provider.request({
+ *   method: 'eth_sendTransaction',
+ *   params: [toJsonRpcTransaction(tx, { from: relayer })],
+ * });
+ * ```
+ */
+declare function toJsonRpcTransaction(transaction: TransactionRequest, options: {
+    from: Address;
+}): JsonRpcTransaction;
+
+/**
+ * Minimal ABI for `SandboxAllowlistRegistry` — the SANDBOX-ONLY registry implementation.
+ *
+ * The sandbox implementation is the stock `AllowlistRegistry` plus permissionless, sandbox-only
+ * helpers (`sandboxAddSelf()`, v2's `sandboxSetSelfTrait()`, and v3's `sandboxRegisterIssuer()`).
+ * It runs behind the registry proxy in a sandbox deployment, so there is no separate helper address: this ABI is used against
+ * the `allowlistRegistry` address from discovery or the built-in `SANDBOX_DEPLOYMENTS` entry, and
+ * only works while that proxy exposes the sandbox implementation.
+ *
+ * Covers the writes this module builds (`sandboxAddSelf`, `sandboxSetSelfTrait`), the marker view
+ * that identifies the sandbox implementation behind a proxy (`sandboxVersion`), the reads a
+ * consumer verifies results with (`isAllowed`, `getUserId`, `hasGlobalTrait`), their emitted trait
+ * event, and every error reachable from those writes:
+ *
+ * - `EnforcedPause()` — the `whenNotPaused` modifier (OpenZeppelin `PausableUpgradeable`) when the
+ *   registry is paused.
+ * - `AddressNotEligible(address)` — the parent `_addToAllowlist` when the sender's entry is in a
+ *   TERMINAL status (`COMPLIANCE_REMOVAL` or `MIGRATED`); those cannot be re-added by any path.
+ * - `AddressNotVerified(address)` — `sandboxSetSelfTrait` requires its caller to be verified first.
+ * - `InvalidUserId()` — the caller has no usable userId binding.
+ * - `InvalidTraitId()` — `traitId` is zero.
+ */
+declare const sandboxAllowlistRegistryAbi: readonly [{
+    readonly type: "function";
+    readonly name: "sandboxRegisterIssuer";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "sandboxAddSelf";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "sandboxSetSelfTrait";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "traitId";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "enabled";
+        readonly type: "bool";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "sandboxVersion";
+    readonly stateMutability: "pure";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "isAllowed";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "getUserId";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bytes32";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "hasGlobalTrait";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "userId";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "traitId";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "GlobalTraitSet";
+    readonly anonymous: false;
+    readonly inputs: readonly [{
+        readonly name: "userId";
+        readonly type: "bytes32";
+        readonly indexed: true;
+    }, {
+        readonly name: "traitId";
+        readonly type: "bytes32";
+        readonly indexed: true;
+    }, {
+        readonly name: "enabled";
+        readonly type: "bool";
+        readonly indexed: false;
+    }, {
+        readonly name: "updatedBy";
+        readonly type: "address";
+        readonly indexed: false;
+    }];
+}, {
+    readonly type: "error";
+    readonly name: "EnforcedPause";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "AddressNotEligible";
+    readonly inputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "error";
+    readonly name: "AddressNotVerified";
+    readonly inputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "error";
+    readonly name: "InvalidUserId";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "InvalidTraitId";
+    readonly inputs: readonly [];
+}];
+/**
+ * What `sandboxVersion()` returns on the SDK's target sandbox implementation source.
+ *
+ * Mirrors the `return 3` in the deployed `SandboxAllowlistRegistry.sol`. A lower live version
+ * exposes fewer sandbox capabilities; a higher one is a newer surface this SDK may not know yet.
+ */
+declare const SANDBOX_IMPLEMENTATION_VERSION = 3n;
+/**
+ * Named trait ids used by the current sandbox product flow.
+ *
+ * `sandboxSetSelfTrait` itself accepts ANY non-zero `bytes32`; these are conveniences, not an
+ * allowlist. `mmfDocumentSigned` is specifically the current MMF subscription document version.
+ * Use `documentTraitId(<versioned canonical name>)` for another document or offering.
+ */
+declare const SANDBOX_TRAIT_IDS: Readonly<{
+    /** `keccak256("trait.accredited")` — the contracts' canonical accredited-investor trait. */
+    readonly accreditedInvestor: `0x${string}`;
+    /** `keccak256("doc.mmf.subscription.v1")` — the current MMF subscription document trait. */
+    readonly mmfDocumentSigned: `0x${string}`;
+}>;
+/**
+ * Which registry proxy, on which chain, and optionally which wallet sends.
+ *
+ * Unlike the attestation flow there is no separate helper contract to point at: `registryAddress`
+ * is exactly the sandbox deployment's `allowlistRegistry` proxy returned by the discovery endpoint
+ * (`GET /chains/:chain_id/attestor`) — or, for a chain with a built-in entry,
+ * `SANDBOX_DEPLOYMENTS[chainId].allowlistRegistry`.
+ */
+interface BuildSandboxAddSelfTransactionParams {
+    /** The allowlist-registry PROXY address — the same one discovery returns. */
+    registryAddress: Address;
+    /** Chain the registry proxy is deployed on. */
+    chainId: number;
+    /**
+     * Optional expected sender recorded as JSON-RPC `from`. If supplied it MUST be the investor's
+     * own wallet. A viem caller must ALSO pass the same wallet as `account`; prefer the ABI-level
+     * builder when account binding is desired.
+     */
+    from?: Address;
+}
+/**
+ * Builds the `sandboxAddSelf()` transaction — a SANDBOX-ONLY, permissionless KYC bypass.
+ *
+ * **SANDBOX ONLY.** `sandboxAddSelf` exists only on the `SandboxAllowlistRegistry` implementation,
+ * a deliberate, total KYC bypass for throwaway sandbox deployments. It must NEVER point at a
+ * production registry; on production implementations this calldata reverts with an unknown
+ * selector.
+ *
+ * **The SENDER is who gets allowlisted.** This is the exact opposite of `attestDocument`'s
+ * permissionless relay: the contract allowlists `msg.sender`, so this transaction CANNOT be
+ * relayed on an investor's behalf. The investor's own wallet must send it, and that wallet pays
+ * the gas.
+ *
+ * `registryAddress` is the same allowlist-registry proxy discovery returns (`allowlistRegistry`
+ * from `GET /chains/:chain_id/attestor`) — same address, same events.
+ *
+ * On success the sender holds a VERIFIED allowlist entry stamped with the registry's default
+ * expiry window, and on the FIRST call the wallet is bound to the deterministic userId
+ * {@link sandboxUserId} computes. With viem, pass the investor explicitly as `account` when
+ * sending; the raw descriptor's `from` is not an account-selection mechanism. See
+ * {@link toSandboxAddSelfWriteContractRequest} for an ABI-level request whose `account` is bound,
+ * and `toJsonRpcTransaction` from `transaction.ts` for a raw EIP-1193 provider.
+ *
+ * @throws {import('../errors.js').OpacityAttestationError} when `registryAddress`, `chainId` or
+ *   `from` is malformed or zero.
+ */
+declare function buildSandboxAddSelfTransaction(params: BuildSandboxAddSelfTransactionParams): TransactionRequest;
+/** The ABI-level form of the same call, for viem `writeContract` / wagmi `useWriteContract`. */
+interface SandboxAddSelfWriteContractRequest {
+    address: Address;
+    abi: typeof sandboxAllowlistRegistryAbi;
+    functionName: 'sandboxAddSelf';
+    args: readonly [];
+    chainId: number;
+    /** Present only when the caller pinned a `from` — the investor wallet that must send. */
+    account?: Address;
+}
+/**
+ * The same SANDBOX-ONLY call expressed as contract arguments rather than calldata.
+ *
+ * Preferred by wagmi users, and it gives viem the ABI it needs to decode a revert into a named
+ * error (`EnforcedPause`, `AddressNotEligible`) instead of a bare selector. All the warnings on
+ * {@link buildSandboxAddSelfTransaction} apply verbatim — sandbox only, and whichever account
+ * sends this request is the one that gets allowlisted; a supplied `from` becomes `account`.
+ *
+ * ```ts
+ * writeContract(toSandboxAddSelfWriteContractRequest({ registryAddress, chainId }));
+ * ```
+ */
+declare function toSandboxAddSelfWriteContractRequest(params: BuildSandboxAddSelfTransactionParams): SandboxAddSelfWriteContractRequest;
+/** Sandbox v3 issuer registration uses the same caller/registry binding as self-onboarding. */
+type BuildSandboxRegisterIssuerTransactionParams = BuildSandboxAddSelfTransactionParams;
+/** Onboard and authorize the sending wallet as an issuer, without an operator transaction. */
+declare function buildSandboxRegisterIssuerTransaction(params: BuildSandboxRegisterIssuerTransactionParams): TransactionRequest;
+/** ABI-level registration request for the issuer's own wallet. Requires a v3 registry. */
+type SandboxRegisterIssuerWriteContractRequest = Omit<SandboxAddSelfWriteContractRequest, 'functionName'> & {
+    functionName: 'sandboxRegisterIssuer';
+};
+declare function toSandboxRegisterIssuerWriteContractRequest(params: BuildSandboxRegisterIssuerTransactionParams): SandboxRegisterIssuerWriteContractRequest;
+/** Inputs shared by the calldata and ABI-level `sandboxSetSelfTrait` builders. */
+interface BuildSandboxSetSelfTraitTransactionParams {
+    /** The allowlist-registry PROXY running `SandboxAllowlistRegistry` v2 or newer. */
+    registryAddress: Address;
+    /** Chain the registry proxy is deployed on. */
+    chainId: number;
+    /** Any non-zero global trait id. See {@link SANDBOX_TRAIT_IDS} for current presets. */
+    traitId: Hex;
+    /** `true` grants the trait; `false` clears it. */
+    enabled: boolean;
+    /**
+     * Optional expected sender as JSON-RPC `from`; viem callers must also select it as `account`.
+     * This wallet's own userId receives (or loses) the trait.
+     */
+    from?: Address;
+}
+/**
+ * Builds a `sandboxSetSelfTrait(bytes32,bool)` transaction for the caller's own global trait.
+ *
+ * **SANDBOX v2 OR NEWER.** This is a deliberate KYC/document/compliance bypass and is absent from the
+ * production registry and sandbox v1. The sending wallet must already have VERIFIED status —
+ * normally by sending {@link buildSandboxAddSelfTransaction} first — and the trait is written to
+ * that wallet's existing userId. There is deliberately no combined add+trait transaction.
+ *
+ * `traitId` can be any non-zero `bytes32`. `enabled: true` grants it; `enabled: false` clears it.
+ * Both directions emit `GlobalTraitSet` with `updatedBy` equal to the sending wallet.
+ *
+ * @throws {import('../errors.js').OpacityAttestationError} when an address, `chainId`, `traitId`,
+ *   or `enabled` is malformed; zero `traitId` is rejected locally as `InvalidTraitId`.
+ */
+declare function buildSandboxSetSelfTraitTransaction(params: BuildSandboxSetSelfTraitTransactionParams): TransactionRequest;
+/** ABI-level form of `sandboxSetSelfTrait`, for viem/wagmi `writeContract`. */
+interface SandboxSetSelfTraitWriteContractRequest {
+    address: Address;
+    abi: typeof sandboxAllowlistRegistryAbi;
+    functionName: 'sandboxSetSelfTrait';
+    args: readonly [traitId: Hex, enabled: boolean];
+    chainId: number;
+    /** Present only when the caller pins the wallet whose own trait will change. */
+    account?: Address;
+}
+/**
+ * Expresses the same sandbox-v2 trait write as ABI + args for viem/wagmi.
+ *
+ * All warnings and validation on {@link buildSandboxSetSelfTraitTransaction} apply. A supplied
+ * `from` becomes `account`; that account must send the transaction and is the identity modified.
+ */
+declare function toSandboxSetSelfTraitWriteContractRequest(params: BuildSandboxSetSelfTraitTransactionParams): SandboxSetSelfTraitWriteContractRequest;
+/**
+ * The deterministic userId `sandboxAddSelf` binds a wallet to on its FIRST call:
+ * `keccak256(abi.encodePacked("sandbox.user.", wallet))` — the 13 UTF-8 bytes of the prefix
+ * concatenated with the 20 address bytes, PACKED, not ABI-padded.
+ *
+ * Checksum-insensitive: the address is normalised before hashing, so any casing of the same
+ * address produces the same id.
+ *
+ * This predicts the userId ONLY for the first-call binding. A wallet previously onboarded through
+ * another path (TEE batch, compliance admin, …) already has a userId, and `sandboxAddSelf` keeps
+ * that existing binding — read the real one back with `getUserId(wallet)` rather than assuming
+ * this value.
+ *
+ * @throws {import('../errors.js').OpacityAttestationError} when `wallet` is malformed or zero.
+ */
+declare function sandboxUserId(wallet: Address): Hex;
+/**
+ * The RPC capabilities {@link probeSandboxRegistry} needs: bytecode lookup, chain identity, and
+ * `eth_call`.
+ *
+ * A structural subset of viem's `PublicClient` — pass the public client your app already has
+ * (wagmi's `usePublicClient()`, or `createPublicClient`). The SDK never opens an RPC connection
+ * of its own, which is why this is a parameter and not configuration it resolves.
+ */
+interface SandboxProbeClient {
+    /** Named `getBytecode` for compatibility with the full declared viem v2 peer range. */
+    getBytecode(args: {
+        address: Address;
+    }): Promise<Hex | undefined>;
+    getChainId(): Promise<number>;
+    call(args: {
+        to: Address;
+        data: Hex;
+        account?: Address;
+    }): Promise<{
+        data?: Hex | undefined;
+    }>;
+}
+interface ProbeSandboxRegistryParams {
+    /** The allowlist-registry PROXY to inspect. */
+    registryAddress: Address;
+    /** Expected RPC chain. Required so a wrong-network reader can never produce a verdict. */
+    chainId: number;
+    /**
+     * Sender to impersonate in the legacy `sandboxAddSelf()` `eth_call` — the investor's wallet,
+     * typically, so a `self_add_revert` verdict is about THEIR entry. Defaults to a nobody address.
+     * Nothing is sent either way.
+     */
+    from?: Address;
+}
+/**
+ * How {@link probeSandboxRegistry} reached its verdict, most to least direct.
+ *
+ * - `marker` — `sandboxVersion()` answered. A sandbox implementation with the marker (source from
+ *   2026-09-01 on) is attached; `version` carries the answer.
+ * - `self_add_call` — the marker reverted, but an `eth_call` of `sandboxAddSelf()` from `from`
+ *   returned the empty data its no-output ABI requires. This is compatibility evidence for an
+ *   older, PRE-marker sandbox implementation, but is necessarily heuristic because a foreign
+ *   contract can have a permissive empty fallback.
+ * - `self_add_revert` — `sandboxAddSelf()` exists but refused the probe sender with one of its own
+ *   errors (`EnforcedPause`, `AddressNotEligible`). The sandbox IS attached; the real transaction
+ *   from that sender would revert the same way right now.
+ * - `not_sandbox` — the marker returned an invalid/empty answer, or both selectors reverted with no
+ *   sandbox registry error. A stock `AllowlistRegistry` (or something else) answers here.
+ * - `no_code` — bytecode lookup proved nothing is deployed at the address.
+ */
+type SandboxProbeEvidence = 'marker' | 'self_add_call' | 'self_add_revert' | 'not_sandbox' | 'no_code';
+/** The verdict of {@link probeSandboxRegistry}. */
+interface SandboxRegistryProbe {
+    /** The registry that was inspected, checksummed. */
+    registryAddress: Address;
+    /** Whether a `SandboxAllowlistRegistry` implementation answers behind the proxy. */
+    attached: boolean;
+    /**
+     * `sandboxVersion()` when the implementation exposes it; `null` for a pre-marker sandbox
+     * implementation and for anything that is not the sandbox. Version 2 or newer is required for
+     * `sandboxSetSelfTrait`.
+     */
+    version: bigint | null;
+    /** How the verdict was reached. See {@link SandboxProbeEvidence}. */
+    evidence: SandboxProbeEvidence;
+}
+/**
+ * Asks a registry proxy, on-chain, whether the sandbox implementation is attached — BEFORE an
+ * investor is prompted to send `sandboxAddSelf()`.
+ *
+ * The sandbox registry is upgradeable, so an address alone does not prove which implementation
+ * currently answers behind it. Two read-only `eth_call`s settle it:
+ *
+ * 1. `sandboxVersion()` — the marker the contracts added for exactly this purpose. Present, and
+ *    the answer is the verdict (`marker`).
+ * 2. Otherwise `sandboxAddSelf()` itself, simulated from `from`. Older sandbox implementations
+ *    deployed before the marker existed have the function but not the view. Its expected empty
+ *    return (or a sandbox-specific revert) is a compatibility signal (`self_add_call` /
+ *    `self_add_revert`), not cryptographic proof: a permissive fallback can imitate empty success.
+ *    Marker-based version detection is authoritative for v1+.
+ *
+ * The reader's chain is checked first, then bytecode, because a wrong network or an empty account
+ * must never produce a verdict. Only an execution REVERT is treated as an answer; a transport
+ * failure propagates as thrown by the client, so a flaky node never reads as "not a sandbox".
+ *
+ * ```ts
+ * const probe = await probeSandboxRegistry(publicClient, {
+ *   registryAddress,
+ *   chainId: 11155111,
+ *   from: investor,
+ * });
+ * if (!probe.attached) showError('This registry is not running the sandbox implementation.');
+ * ```
+ *
+ * @throws {import('../errors.js').OpacityAttestationError} when `registryAddress`, `chainId`, or
+ *   `from` is malformed or zero.
+ * @throws {import('../errors.js').OpacityConfigError} when the reader is connected to a different
+ *   chain than `chainId`.
+ * @throws whatever the RPC client throws for a non-revert failure, untouched.
+ */
+declare function probeSandboxRegistry(client: SandboxProbeClient, params: ProbeSandboxRegistryParams): Promise<SandboxRegistryProbe>;
+
+/**
+ * Sepolia's chain id — the one chain the shared Opacity sandbox is deployed on today.
+ */
+declare const SEPOLIA_CHAIN_ID = 11155111;
+/**
+ * The chain `client.sandbox` assumes when the client has no `chainId` configured and none is
+ * passed per call. Sepolia, for now: it is the only chain with a sandbox deployment, so it is the
+ * only honest default. `client.documents` deliberately does NOT inherit this default — the
+ * attestation flow is chain-agnostic and refuses to guess.
+ */
+declare const SANDBOX_CHAIN_ID = 11155111;
+/**
+ * The document/onboarding addresses of one sandbox deployment. Purchase vault/token/payment
+ * addresses are separately pinned in `SANDBOX_PURCHASE_DEPLOYMENT`.
+ *
+ * The sandbox registry is upgradeable, so `allowlistRegistry` is the proxy address rather than
+ * its current implementation. The Sepolia sandbox is a dedicated deployment initialized with
+ * `SandboxAllowlistRegistry`; whether that implementation still answers is a live question — see
+ * `probeSandboxRegistry`.
+ */
+interface SandboxDeployment {
+    /** The chain these addresses live on. */
+    chainId: number;
+    /** The allowlist-registry PROXY running `SandboxAllowlistRegistry`. The target of `sandboxAddSelf()`. */
+    allowlistRegistry: Address;
+    /**
+     * The `DocumentAttestor` wired as that registry's trait writer — the EIP-712 `verifyingContract`
+     * of every session the sandbox backend issues. Pin it as `expectedAttestor` when you want the
+     * wallet prompt refused if discovery ever disagrees.
+     */
+    documentAttestor: Address;
+}
+/**
+ * Built-in sandbox deployments, keyed by chain id. Sepolia only, today.
+ *
+ * These and `SANDBOX_PURCHASE_DEPLOYMENT` are testnet-only constants; production addresses are
+ * never baked in. They serve as
+ * the FALLBACK for `client.sandbox` when discovery cannot answer, and as constants a consumer can
+ * pin (`expectedAttestor`) or use with the pure builders without a backend at all.
+ *
+ * Source and receipt provenance: SEPOLIA_SANDBOX_MANIFEST and
+ * deployments/sepolia-sandbox-v3.json. Verified sandboxVersion() = 3 after all
+ * deployment and MMF seed transactions confirmed. Discovery remains backend-owned;
+ * pin these addresses explicitly during the subgraph/backend cutover.
+ */
+declare const SANDBOX_DEPLOYMENTS: Readonly<Partial<Record<number, SandboxDeployment>>>;
+/** The built-in sandbox deployment for a chain, or `undefined` when the SDK ships none for it. */
+declare function getSandboxDeployment(chainId: number): SandboxDeployment | undefined;
+/**
+ * The built-in sandbox deployment for a chain, or an error naming the chains that have one.
+ *
+ * @throws {OpacityConfigError} when no built-in deployment exists for `chainId`.
+ */
+declare function requireSandboxDeployment(chainId: number): SandboxDeployment;
+
+/** One entry of an EIP-712 struct definition, as it arrives over the wire. */
+interface Eip712TypeField {
+    name: string;
+    type: string;
+}
+/**
+ * The `typedData` block of a create response, exactly as the backend sends it.
+ *
+ * JSON-shaped: `deadline` is a decimal STRING because JSON cannot carry a `bigint`, and `types`
+ * declares `EIP712Domain` alongside `DocumentAcceptance`.
+ *
+ * **Signable as it arrives on a raw `eth_signTypedData_v4` provider.** That method wants exactly
+ * this JSON form, and mobile-api already declares `EIP712Domain` in `types`, so no reshaping is
+ * needed. {@link toEip1193Json} / {@link toEip1193TypedData} remain worthwhile there for their
+ * validation and attestor pinning, not because the payload needs repair.
+ *
+ * **viem and wagmi also take it as it arrives.** viem parses the decimal-string `uint256` to the
+ * same digest a `bigint` produces, and ignores the extra `EIP712Domain` entry. Run it through
+ * {@link toViemTypedData} anyway — for the validation and the `expectedAttestor` /
+ * `expectedChainId` pinning, not for correctness.
+ *
+ * **ethers v6 is the one stack that cannot take it**, and that is the hard requirement
+ * {@link toViemTypedData} exists to satisfy. `TypedDataEncoder` rejects a `types` map that declares
+ * the domain, throwing `ambiguous primary types or unused types: "EIP712Domain",
+ * "DocumentAcceptance"` — so the raw payload never reaches an ethers signer at all. Route it
+ * through {@link toViemTypedData} (whose `types` is this SDK's constant, with no `EIP712Domain`
+ * entry) and then `toEthersTypedData`.
+ */
+interface ServerAttestationTypedData {
+    domain: {
+        name: string;
+        version: string;
+        chainId: number;
+        verifyingContract: Address;
+    };
+    types: Record<string, readonly Eip712TypeField[]>;
+    primaryType: string;
+    message: {
+        nonce: Hex;
+        docHash: Hex;
+        /** Decimal string of unix seconds. NOT a number, and NOT a bigint. */
+        deadline: string;
+    };
+}
+/** Optional domain pinning for {@link toViemTypedData}. */
+interface ToViemTypedDataOptions {
+    /**
+     * The `DocumentAttestor` address this client will accept, checked against
+     * `typedData.domain.verifyingContract`.
+     *
+     * Supplying it is defence in depth and costs nothing: a client that blindly signs whatever
+     * domain arrives over the wire has no independent anchor on which contract it is authorising, so
+     * a compromised or merely misconfigured backend could aim a valid-looking prompt at a different
+     * deployment. The investor cannot tell those apart; a pinned constant can.
+     */
+    expectedAttestor?: Address;
+    /** The chain id this client will accept, checked against `typedData.domain.chainId`. */
+    expectedChainId?: number;
+}
+/**
+ * Validates the backend's JSON `typedData` and returns it in this SDK's own viem-shaped form — the
+ * one `toEthersTypedData`, `toEip712JsonPayload` and `hashDocumentAcceptance` all take.
+ *
+ * **Only ethers strictly needs it, and not for the reason you would guess.** The `deadline`
+ * reshaping is cosmetic: viem and ethers both hash the wire's decimal-string `uint256` to the same
+ * digest as the `bigint` this returns. What ethers v6 will NOT accept is the `EIP712Domain` entry
+ * mobile-api declares in `types` — `TypedDataEncoder` throws `ambiguous primary types or unused
+ * types: "EIP712Domain", "DocumentAcceptance"` — so the server's payload cannot reach an ethers
+ * signer at all. This function's `types` is the SDK's own constant, which omits that entry, which
+ * is what makes the `toEthersTypedData` hand-off work.
+ *
+ * **viem, wagmi and a raw `eth_signTypedData_v4` provider all accept `session.typedData` as it
+ * arrives.** viem tolerates both the decimal string and the extra `EIP712Domain` entry;
+ * `eth_signTypedData_v4` is specified in terms of exactly that JSON shape. Use this function on
+ * those paths for what it validates and pins, not because the payload needs repair — and use
+ * {@link toEip1193Json} for the EIP-1193 one, which runs these same checks and re-serialises.
+ *
+ * Everything else this function does is validation, because the payload it is handed decides what
+ * a human is about to authorise:
+ *
+ * - `primaryType` must be `DocumentAcceptance`.
+ * - The `DocumentAcceptance` field list must match {@link DOCUMENT_ACCEPTANCE_TYPES} exactly —
+ *   same names, same types, same ORDER. Order is consensus-critical: it is part of the type hash,
+ *   and a reordered list produces a valid signature over a different struct. Unreferenced extra
+ *   entries in `types` are ignored: the encoding of this payload is fully determined by the primary
+ *   type's field list, all of which are atomic, so an unused extra type cannot change the digest.
+ * - `EIP712Domain` is the one exception to that, and mobile-api declares it on EVERY session — so
+ *   this check runs on the normal path, not on a hypothetical future one. A declaration matching
+ *   {@link EIP712_DOMAIN_TYPE} is accepted; any other declaration — including the empty list — is
+ *   rejected, because that entry is not inert. It replaces the domain type a wallet would otherwise
+ *   derive, so a wrong one re-hashes the domain and moves the digest. An absent entry is tolerated
+ *   too, since viem and ethers derive the type themselves and this SDK re-declares it on the
+ *   EIP-1193 path.
+ * - The domain `name`/`version` must be `DocumentAttestor`/`1`, and `chainId` /
+ *   `verifyingContract` must be well-formed.
+ * - `nonce` and `docHash` must be well-formed `bytes32`, and `docHash` non-zero.
+ *
+ * Pass {@link ToViemTypedDataOptions} to additionally pin the domain to a deployment this client
+ * already knows about. Optional, and worth taking: see the field docs for why blind signing leaves
+ * the client with no independent anchor.
+ *
+ * The returned `types` object is this SDK's own constant rather than the server's array. That is
+ * safe precisely because the check above proved the two are identical field for field, and it
+ * means the result is the same `DocumentAcceptanceTypedData` the local builder produces — so
+ * `toEthersTypedData`, `toEip712JsonPayload` and `hashDocumentAcceptance` all accept it.
+ *
+ * @throws {import('../errors.js').OpacityAttestationError} on any mismatch. Nothing is coerced
+ *   silently; a payload that does not validate must not reach a wallet.
+ */
+declare function toViemTypedData(typedData: ServerAttestationTypedData, options?: ToViemTypedDataOptions): DocumentAcceptanceTypedData;
+/**
+ * Converts the backend's JSON `typedData` into a payload a raw EIP-1193 provider can sign, and
+ * validates it on the way through.
+ *
+ * ```ts
+ * const signature = await provider.request({
+ *   method: 'eth_signTypedData_v4',
+ *   params: [account, toEip1193Json(session.typedData, { expectedAttestor, expectedChainId })],
+ * });
+ * ```
+ *
+ * Sending `session.typedData` as it arrives is FINE — mobile-api declares `EIP712Domain`
+ * alongside `DocumentAcceptance`, which is what makes it safe. This function is the belt-and-braces
+ * route: it validates and pins the payload before a wallet ever sees it.
+ *
+ * What it guards against is a `types` map that declares `EIP712Domain` INCORRECTLY, or omits it.
+ * `eth_signTypedData_v4` implementations built on MetaMask's `eth-sig-util` sanitise with
+ * `{ EIP712Domain: [], ...types }`, so a missing entry becomes an EMPTY field list rather than an
+ * error. The domain then hashes as `keccak256("EIP712Domain()")` — no `name`, no `version`, no
+ * `chainId`, no `verifyingContract` — and the digest changes:
+ *
+ * ```text
+ * EIP712Domain declared     0x91feb0709c4ebdff9ccc57b12b26c50936eae7973f67c6d23780fcfdbda3f410  ✓
+ * EIP712Domain defaulted [] 0x82ada7044278f3b529058b2dac44bb987f078c23b15195e1dca77110f0c91691  ✗
+ * ```
+ *
+ * Nothing throws. The wallet shows the right prompt and returns a well-formed signature over a
+ * digest the contract has never heard of, and the failure surfaces much later as an
+ * `InvalidUserSignature` from the relay's simulate step — which reads like "your wallet is
+ * broken", not "the payload was missing a type". That is why {@link assertDomainFieldsIfDeclared}
+ * rejects a MALFORMED `EIP712Domain` rather than quietly replacing it: the SDK will not hand a
+ * wallet a payload whose domain type it cannot vouch for.
+ *
+ * The conversion runs {@link toViemTypedData} first, so every check listed there applies — the
+ * primary type, the field list and its ORDER, the domain, and the optional
+ * {@link ToViemTypedDataOptions} pinning — and then {@link toEip712JsonPayload} re-serialises with
+ * `EIP712Domain` declared and `deadline` back to a decimal string. That round trip through a
+ * `bigint` is deliberate: it is what proves the string the wallet receives is a well-formed
+ * `uint256` rather than whatever the wire happened to carry.
+ *
+ * @throws {import('../errors.js').OpacityAttestationError} on any mismatch, exactly as
+ *   {@link toViemTypedData} does. A payload that does not validate must not reach a wallet.
+ */
+declare function toEip1193TypedData(typedData: ServerAttestationTypedData, options?: ToViemTypedDataOptions): Eip712JsonPayload;
+/**
+ * {@link toEip1193TypedData}, serialised — the second `eth_signTypedData_v4` parameter.
+ *
+ * Providers differ on whether they want the object or the JSON string; the string is accepted
+ * everywhere, so this is the safer default. Same validation, same reason for existing: see
+ * {@link toEip1193TypedData} for the digest that silently changes without it.
+ *
+ * @throws {import('../errors.js').OpacityAttestationError} on any mismatch.
+ */
+declare function toEip1193Json(typedData: ServerAttestationTypedData, options?: ToViemTypedDataOptions): string;
+
+export { type AttestationSessionResponseLike, BuildAttestDocumentTransactionParams, BuildDocumentAcceptanceTypedDataParams, type BuildSandboxAddSelfTransactionParams, type BuildSandboxRegisterIssuerTransactionParams, type BuildSandboxSetSelfTraitTransactionParams, ClockOptions, DOCUMENT_ACCEPTANCE_PRIMARY_TYPE, DOCUMENT_ACCEPTANCE_TYPEHASH, DOCUMENT_ACCEPTANCE_TYPES, DOCUMENT_ATTESTOR_DOMAIN_NAME, DOCUMENT_ATTESTOR_DOMAIN_VERSION, type DocumentAcceptanceMessage, type DocumentAcceptanceTypedData, type DocumentAttestorDomain, ECDSA_SIGNATURE_BYTES, EIP712_DOMAIN_TYPE, type Eip712JsonPayload, type Eip712TypeField, type EthersTypedData, type JsonRpcTransaction, MAX_ATTESTATION_LIFETIME_SECONDS, type ProbeSandboxRegistryParams, SANDBOX_CHAIN_ID, SANDBOX_DEPLOYMENTS, SANDBOX_IMPLEMENTATION_VERSION, SANDBOX_TRAIT_IDS, SEPOLIA_CHAIN_ID, type SandboxAddSelfWriteContractRequest, type SandboxDeployment, type SandboxProbeClient, type SandboxProbeEvidence, type SandboxRegisterIssuerWriteContractRequest, type SandboxRegistryProbe, type SandboxSetSelfTraitWriteContractRequest, type ServerAttestationTypedData, type ToViemTypedDataOptions, TransactionRequest, type VerifyAttestationSessionFields, type VerifyAttestationSessionParams, type VerifyAttestationSessionResponseParams, type WriteContractRequest, assertDocumentMatchesHash, buildAttestDocumentTransaction, buildDocumentAcceptanceTypedData, buildSandboxAddSelfTransaction, buildSandboxRegisterIssuerTransaction, buildSandboxSetSelfTraitTransaction, documentAttestorAbi, documentTraitId, getSandboxDeployment, hashDocument, hashDocumentAcceptance, probeSandboxRegistry, requireSandboxDeployment, sandboxAllowlistRegistryAbi, sandboxUserId, toEip1193Json, toEip1193TypedData, toEip712Json, toEip712JsonPayload, toEthersTypedData, toJsonRpcTransaction, toSandboxAddSelfWriteContractRequest, toSandboxRegisterIssuerWriteContractRequest, toSandboxSetSelfTraitWriteContractRequest, toViemTypedData, toWriteContractRequest, verifyAttestationSession };