opacity-issuer-core 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Opacity Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,44 @@
+# opacity-issuer-core
+
+Backend-independent Opacity protocol helpers, contract ABIs, policy builders, issuer lifecycle, purchases, and document signing primitives. This package does not require mobile-api configuration or authentication.
+
+```ts
+import { createIssuersNamespace } from 'opacity-issuer-core';
+import { createSubgraphClient, createIndexerNamespace } from 'opacity-issuer-core/subgraph';
+
+const issuers = createIssuersNamespace({ chainId, publicClient, walletClient });
+const subgraph = createSubgraphClient({ url: process.env.SUBGRAPH_URL! });
+const data = await subgraph.query<{ tokens: { id: string }[] }>('{ tokens { id } }');
+const indexer = createIndexerNamespace({ url: process.env.SUBGRAPH_URL! });
+const balances = await indexer.listBalances({ wallet });
+```
+
+Keep authenticated subgraph URLs and headers in your application's server configuration. The direct clients share one HTTP transport, default to global `fetch` with a 30-second deadline, and accept cancellation and timeout overrides; the generic client also accepts headers and an injected fetch implementation so the application controls caching. HTTP failures, GraphQL errors (including partial responses), and absent data objects reject.
+
+`opacity-issuer-core/subgraph` also exports the fixed hosted API operation list, lossless bigint wire helpers, and the shared operation argument and response validators used by the SDK and mobile-api. The same argument contract validates direct reads and decoded hosted requests, including unknown keys, uint256 quantities, snapshot bounds and cursor shapes. API adapters can apply tighter request budgets. These helpers do not choose an upstream endpoint.
+
+Use `opacity-issuer-sdk` for external frontend integrations that route reads, user status, document sessions and relay through mobile-api. Core supplies protocol capabilities; application authentication, organization authorization, private signing keys, offchain document records and relayer infrastructure remain application/backend responsibilities.
+
+For sandbox fixtures, `prepareSandboxUser(publicClient, { chainId, registryAddress, wallet,
+traits: { accredited: true, jurisdictions: { US: true } } })` prepares only needed onboarding and
+global trait writes from live state. Send the returned steps with the test wallet through
+`createIssuersNamespace`. `resolveSandboxUserTraits`, `sandboxTraitId`, and
+`sandboxJurisdictionTraitId` also work offline. Profiles are patches; document traits bypass a
+policy gate without creating signed-document history. See the
+[sandbox user guide](https://github.com/OpacityLabs/opacity-issuer-sdk/blob/main/docs/sandbox-users.md).
+
+To create a separate random test wallet, use `createSandboxUser(publicClient, { chainId,
+registryAddress, transport, traits, funding: { walletClient: sponsor, amount }, persist })`.
+The sponsor approves one exact native-currency transfer; the generated wallet automatically signs
+onboarding and trait writes. Funding is optional, has no default amount, and never retries automatically.
+Credentials are persisted before writes and returned with progress for recovery.
+Supply a saved test `privateKey` to reuse it. The read client and write transport must agree on
+chain. `waitForSandboxUserFunding` reconciles a saved funding transfer without resending it.
+
+### Token transfers
+
+`createTransfersNamespace({ chainId, publicClient, walletClient })` provides `prepareTransfer`,
+`sendTransfer`, and `waitForTransfer` for normal ERC1155 SecurityToken transfers. It checks live
+policies and gas and verifies the exact transfer receipt. `transferSandboxUser` adds optional
+one-transfer gas sponsorship and persistent progress for a saved local demo signer.
+See [transfer integration](../../docs/transfers.md).

package/dist/chunk-2STMWRIV.js

@@ -0,0 +1,164 @@
+import { OpacityAttestationError } from './chunk-54Q3MU62.js';
+import { isAddress, getAddress, isHex, size } from 'viem';
+
+// src/documents/constants.ts
+var DOCUMENT_ATTESTOR_DOMAIN_NAME = "DocumentAttestor";
+var DOCUMENT_ATTESTOR_DOMAIN_VERSION = "1";
+var DOCUMENT_ACCEPTANCE_TYPES = {
+  DocumentAcceptance: [
+    { name: "nonce", type: "bytes32" },
+    { name: "docHash", type: "bytes32" },
+    { name: "deadline", type: "uint256" }
+  ]
+};
+var DOCUMENT_ACCEPTANCE_PRIMARY_TYPE = "DocumentAcceptance";
+var EIP712_DOMAIN_TYPE = [
+  { name: "name", type: "string" },
+  { name: "version", type: "string" },
+  { name: "chainId", type: "uint256" },
+  { name: "verifyingContract", type: "address" }
+];
+var DOCUMENT_ACCEPTANCE_TYPEHASH = "0xcd87f8252156623d78fd52f8f4f1c63bcda5d0b21a8c7f56f63a1759103d6598";
+var MAX_ATTESTATION_LIFETIME_SECONDS = 2592000n;
+var ECDSA_SIGNATURE_BYTES = 65;
+
+// src/documents/validate.ts
+var ZERO_BYTES32 = "0x0000000000000000000000000000000000000000000000000000000000000000";
+function assertAddress(value, field) {
+  if (typeof value !== "string" || !isAddress(value, { strict: false })) {
+    throw new OpacityAttestationError("MalformedInput", `\`${field}\` is not a valid address.`, {
+      field
+    });
+  }
+  const normalized = getAddress(value);
+  if (normalized === "0x0000000000000000000000000000000000000000") {
+    throw new OpacityAttestationError("ZeroAddress", `\`${field}\` must not be the zero address.`, {
+      field
+    });
+  }
+  return normalized;
+}
+function assertBytes32(value, field) {
+  if (typeof value !== "string" || !isHex(value) || value.length !== 2 + 64) {
+    throw new OpacityAttestationError(
+      "MalformedInput",
+      `\`${field}\` must be a 32-byte hex string (0x + 64 hex chars).`,
+      { field }
+    );
+  }
+  return value;
+}
+function assertTraitId(value) {
+  const traitId = assertBytes32(value, "traitId");
+  if (traitId.toLowerCase() === ZERO_BYTES32) {
+    throw new OpacityAttestationError("InvalidTraitId", "`traitId` must not be zero.", {
+      field: "traitId"
+    });
+  }
+  return traitId;
+}
+function assertBoolean(value, field) {
+  if (typeof value !== "boolean") {
+    throw new OpacityAttestationError("MalformedInput", `\`${field}\` must be a boolean.`, {
+      field
+    });
+  }
+  return value;
+}
+function assertDocHash(value) {
+  const docHash = assertBytes32(value, "docHash");
+  if (docHash.toLowerCase() === ZERO_BYTES32) {
+    throw new OpacityAttestationError("InvalidDocHash", "`docHash` must not be zero.", {
+      field: "docHash"
+    });
+  }
+  return docHash;
+}
+function assertNonce(value) {
+  return assertBytes32(value, "nonce");
+}
+function assertTimestamp(value, field) {
+  if (typeof value !== "bigint") {
+    throw new OpacityAttestationError(
+      "MalformedInput",
+      `\`${field}\` must be a bigint of unix seconds.`,
+      { field }
+    );
+  }
+  if (value < 0n) {
+    throw new OpacityAttestationError("MalformedInput", `\`${field}\` must not be negative.`, {
+      field
+    });
+  }
+  return value;
+}
+function assertServerSignature(value) {
+  if (typeof value !== "string" || !isHex(value)) {
+    throw new OpacityAttestationError("MalformedInput", "`serverSignature` must be a hex string.", {
+      field: "serverSignature"
+    });
+  }
+  if (value.length !== 2 + ECDSA_SIGNATURE_BYTES * 2) {
+    const length = size(value);
+    throw new OpacityAttestationError(
+      "InvalidSignatureLength",
+      `\`serverSignature\` must be ${ECDSA_SIGNATURE_BYTES} bytes; received ${length}. The document server signs with ECDSA, which accepts no other length.`,
+      { field: "serverSignature" }
+    );
+  }
+  return value;
+}
+function assertUserSignature(value) {
+  if (typeof value !== "string" || !isHex(value) || value.length % 2 !== 0) {
+    throw new OpacityAttestationError(
+      "MalformedInput",
+      "`userSignature` must be a hex string of whole bytes.",
+      { field: "userSignature" }
+    );
+  }
+  return value;
+}
+function assertSessionWindow(session, options = {}) {
+  const { deadline } = session;
+  assertTimestamp(deadline, "deadline");
+  if (session.issuedAt !== void 0) {
+    const issuedAt = assertTimestamp(session.issuedAt, "issuedAt");
+    const maxAllowed = issuedAt + MAX_ATTESTATION_LIFETIME_SECONDS;
+    if (deadline > maxAllowed) {
+      throw new OpacityAttestationError(
+        "AttestationDeadlineTooFar",
+        `\`deadline\` (${deadline}) exceeds \`issuedAt\` + MAX_ATTESTATION_LIFETIME (${maxAllowed}).`,
+        { field: "deadline" }
+      );
+    }
+  }
+  const { now } = options;
+  if (now === void 0) return;
+  assertTimestamp(now, "now");
+  if (session.issuedAt !== void 0 && session.issuedAt > now) {
+    throw new OpacityAttestationError(
+      "AttestationIssuedInFuture",
+      `\`issuedAt\` (${session.issuedAt}) is in the future relative to \`now\` (${now}). A post-dated session is rejected permanently, not held until it matures.`,
+      { field: "issuedAt" }
+    );
+  }
+  if (now > deadline) {
+    throw new OpacityAttestationError(
+      "AttestationExpired",
+      `The session expired at ${deadline}, before \`now\` (${now}).`,
+      { field: "deadline" }
+    );
+  }
+}
+function assertChainId(value) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new OpacityAttestationError("MalformedInput", "`chainId` must be a positive integer.", {
+      field: "chainId"
+    });
+  }
+  return value;
+}
+
+export { DOCUMENT_ACCEPTANCE_PRIMARY_TYPE, DOCUMENT_ACCEPTANCE_TYPEHASH, DOCUMENT_ACCEPTANCE_TYPES, DOCUMENT_ATTESTOR_DOMAIN_NAME, DOCUMENT_ATTESTOR_DOMAIN_VERSION, ECDSA_SIGNATURE_BYTES, EIP712_DOMAIN_TYPE, MAX_ATTESTATION_LIFETIME_SECONDS, assertAddress, assertBoolean, assertBytes32, assertChainId, assertDocHash, assertNonce, assertServerSignature, assertSessionWindow, assertTimestamp, assertTraitId, assertUserSignature };
+//# sourceMappingURL=chunk-2STMWRIV.js.map
+//# sourceMappingURL=chunk-2STMWRIV.js.map

package/dist/chunk-2STMWRIV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/documents/constants.ts","../src/documents/validate.ts"],"names":[],"mappings":"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","file":"chunk-2STMWRIV.js","sourcesContent":["import type { Hex } from 'viem';\n\n/**\n * EIP-712 domain `name` and `version`, from `EIP712(\"DocumentAttestor\", \"1\")` in\n * `DocumentAttestor.sol`. The domain has no `salt` — OpenZeppelin's `EIP712` uses\n * `EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)`.\n */\nexport const DOCUMENT_ATTESTOR_DOMAIN_NAME = 'DocumentAttestor';\nexport const DOCUMENT_ATTESTOR_DOMAIN_VERSION = '1';\n\n/**\n * The payload the investor's wallet signs.\n *\n * It deliberately binds neither `wallet` nor `traitId`: the trait is an internal mapping and the\n * prompt should show only what the human is agreeing to, while the binding to a wallet comes from\n * ECDSA recovery (or, for ERC-1271, from the server's own signature). Cross-deployment and\n * cross-chain replay are stopped by the domain's `chainId` + `verifyingContract`.\n *\n * Field order is consensus-critical — it is part of the type hash.\n */\nexport const DOCUMENT_ACCEPTANCE_TYPES = {\n  DocumentAcceptance: [\n    { name: 'nonce', type: 'bytes32' },\n    { name: 'docHash', type: 'bytes32' },\n    { name: 'deadline', type: 'uint256' },\n  ],\n} as const;\n\nexport const DOCUMENT_ACCEPTANCE_PRIMARY_TYPE = 'DocumentAcceptance';\n\n/**\n * The EIP-712 domain type, needed only by `toEip712JsonPayload`: raw `eth_signTypedData_v4`\n * requires `EIP712Domain` to be present in `types`, whereas viem derives it and ethers v6 throws\n * if you supply it.\n */\nexport const EIP712_DOMAIN_TYPE = [\n  { name: 'name', type: 'string' },\n  { name: 'version', type: 'string' },\n  { name: 'chainId', type: 'uint256' },\n  { name: 'verifyingContract', type: 'address' },\n] as const;\n\n/**\n * `keccak256(\"DocumentAcceptance(bytes32 nonce,bytes32 docHash,uint256 deadline)\")`.\n *\n * Not used to build the payload (viem derives it from {@link DOCUMENT_ACCEPTANCE_TYPES}); exported\n * so a consumer can assert it against the contract's `DOCUMENT_ACCEPTANCE_TYPEHASH()` getter.\n */\nexport const DOCUMENT_ACCEPTANCE_TYPEHASH: Hex =\n  '0xcd87f8252156623d78fd52f8f4f1c63bcda5d0b21a8c7f56f63a1759103d6598';\n\n/**\n * Mirrors `DocumentAttestor.MAX_ATTESTATION_LIFETIME` (30 days).\n *\n * Duplicated off-chain so `deadline > issuedAt + MAX_ATTESTATION_LIFETIME` can be caught before the\n * investor is prompted, rather than at redemption. It is a `constant` on a non-upgradeable contract,\n * so it cannot drift for a given deployment — but a successor deployment could choose a different\n * value, which is why `MAX_ATTESTATION_LIFETIME` is kept in `documentAttestorAbi` for\n * consumers that want to read it back.\n */\nexport const MAX_ATTESTATION_LIFETIME_SECONDS = 2_592_000n;\n\n/** Length in bytes of the ECDSA signature `ECDSA.recover` accepts — it rejects every other length. */\nexport const ECDSA_SIGNATURE_BYTES = 65;\n","import { getAddress, isAddress, isHex, size } from 'viem';\nimport type { Address, Hex } from 'viem';\n\nimport { OpacityAttestationError } from '../errors.js';\nimport { ECDSA_SIGNATURE_BYTES, MAX_ATTESTATION_LIFETIME_SECONDS } from './constants.js';\nimport type { ClockOptions } from './types.js';\n\nconst ZERO_BYTES32 = '0x0000000000000000000000000000000000000000000000000000000000000000';\n\n/**\n * Normalises an address and rejects the zero address.\n *\n * Returns the checksummed form: `attestDocument` takes `wallet` as a plain `address`, so casing\n * does not affect the calldata, but returning the canonical form keeps the descriptor comparable.\n */\nexport function assertAddress(value: Address, field: string): Address {\n  if (typeof value !== 'string' || !isAddress(value, { strict: false })) {\n    throw new OpacityAttestationError('MalformedInput', `\\`${field}\\` is not a valid address.`, {\n      field,\n    });\n  }\n  const normalized = getAddress(value);\n  if (normalized === '0x0000000000000000000000000000000000000000') {\n    throw new OpacityAttestationError('ZeroAddress', `\\`${field}\\` must not be the zero address.`, {\n      field,\n    });\n  }\n  return normalized;\n}\n\n/**\n * Rejects anything that is not 32 bytes of hex. Zero-ness is checked separately, per field.\n *\n * Length is checked on the string, not via `size()`, which rounds a half-byte up — `0x` followed\n * by 63 hex chars has a `size()` of 32 but is not a valid `bytes32`.\n */\nexport function assertBytes32(value: Hex, field: string): Hex {\n  if (typeof value !== 'string' || !isHex(value) || value.length !== 2 + 64) {\n    throw new OpacityAttestationError(\n      'MalformedInput',\n      `\\`${field}\\` must be a 32-byte hex string (0x + 64 hex chars).`,\n      { field },\n    );\n  }\n  return value;\n}\n\n/**\n * `traitId` must be non-zero — `InvalidTraitId`.\n *\n * A zero trait id is almost always an un-set config value rather than a real trait.\n */\nexport function assertTraitId(value: Hex): Hex {\n  const traitId = assertBytes32(value, 'traitId');\n  if (traitId.toLowerCase() === ZERO_BYTES32) {\n    throw new OpacityAttestationError('InvalidTraitId', '`traitId` must not be zero.', {\n      field: 'traitId',\n    });\n  }\n  return traitId;\n}\n\n/** Strict runtime boolean validation for callers that bypass TypeScript declarations. */\nexport function assertBoolean(value: boolean, field: string): boolean {\n  if (typeof value !== 'boolean') {\n    throw new OpacityAttestationError('MalformedInput', `\\`${field}\\` must be a boolean.`, {\n      field,\n    });\n  }\n  return value;\n}\n\n/**\n * `docHash` must be non-zero — `InvalidDocHash`.\n *\n * No executed document hashes to zero, so a zero here is a server-side bug and must not be attested.\n */\nexport function assertDocHash(value: Hex): Hex {\n  const docHash = assertBytes32(value, 'docHash');\n  if (docHash.toLowerCase() === ZERO_BYTES32) {\n    throw new OpacityAttestationError('InvalidDocHash', '`docHash` must not be zero.', {\n      field: 'docHash',\n    });\n  }\n  return docHash;\n}\n\n/**\n * `nonce` must be well-formed, but may be zero.\n *\n * The contract applies no zero-check to the nonce — slot zero is burnable like any other — so\n * rejecting it here would be stricter than the chain.\n */\nexport function assertNonce(value: Hex): Hex {\n  return assertBytes32(value, 'nonce');\n}\n\n/** Rejects negative or non-`bigint` unix timestamps before they are encoded as `uint256`. */\nexport function assertTimestamp(value: bigint, field: string): bigint {\n  if (typeof value !== 'bigint') {\n    throw new OpacityAttestationError(\n      'MalformedInput',\n      `\\`${field}\\` must be a bigint of unix seconds.`,\n      { field },\n    );\n  }\n  if (value < 0n) {\n    throw new OpacityAttestationError('MalformedInput', `\\`${field}\\` must not be negative.`, {\n      field,\n    });\n  }\n  return value;\n}\n\n/**\n * The 65-byte rule for the SERVER signature only.\n *\n * `ECDSA.recover` accepts exactly one length and reverts `ECDSAInvalidSignatureLength` on any\n * other. The investor signature must NOT be length-checked: `SignatureChecker` routes a\n * code-bearing wallet (a Safe, or an EIP-7702-delegated EOA) to ERC-1271, where the signature is\n * whatever that wallet's own validation logic accepts.\n */\nexport function assertServerSignature(value: Hex): Hex {\n  if (typeof value !== 'string' || !isHex(value)) {\n    throw new OpacityAttestationError('MalformedInput', '`serverSignature` must be a hex string.', {\n      field: 'serverSignature',\n    });\n  }\n  if (value.length !== 2 + ECDSA_SIGNATURE_BYTES * 2) {\n    const length = size(value);\n    throw new OpacityAttestationError(\n      'InvalidSignatureLength',\n      `\\`serverSignature\\` must be ${ECDSA_SIGNATURE_BYTES} bytes; received ${length}. ` +\n        'The document server signs with ECDSA, which accepts no other length.',\n      { field: 'serverSignature' },\n    );\n  }\n  return value;\n}\n\n/**\n * The investor signature: hex, any BYTE length — an ERC-1271 wallet is not 65 bytes.\n *\n * Only the half-byte case is rejected, since it cannot encode as `bytes`.\n */\nexport function assertUserSignature(value: Hex): Hex {\n  if (typeof value !== 'string' || !isHex(value) || value.length % 2 !== 0) {\n    throw new OpacityAttestationError(\n      'MalformedInput',\n      '`userSignature` must be a hex string of whole bytes.',\n      { field: 'userSignature' },\n    );\n  }\n  return value;\n}\n\n/**\n * The session-lifetime rules, split by whether they need a clock.\n *\n * `deadline <= issuedAt + MAX_ATTESTATION_LIFETIME` is absolute and always checked. The two\n * clock-relative rules run only when `now` is supplied — see {@link ClockOptions} for why that is\n * opt-in.\n */\nexport function assertSessionWindow(\n  session: { issuedAt?: bigint | undefined; deadline: bigint },\n  options: ClockOptions = {},\n): void {\n  const { deadline } = session;\n  assertTimestamp(deadline, 'deadline');\n\n  if (session.issuedAt !== undefined) {\n    const issuedAt = assertTimestamp(session.issuedAt, 'issuedAt');\n    const maxAllowed = issuedAt + MAX_ATTESTATION_LIFETIME_SECONDS;\n    if (deadline > maxAllowed) {\n      throw new OpacityAttestationError(\n        'AttestationDeadlineTooFar',\n        `\\`deadline\\` (${deadline}) exceeds \\`issuedAt\\` + MAX_ATTESTATION_LIFETIME (${maxAllowed}).`,\n        { field: 'deadline' },\n      );\n    }\n  }\n\n  const { now } = options;\n  if (now === undefined) return;\n  assertTimestamp(now, 'now');\n\n  if (session.issuedAt !== undefined && session.issuedAt > now) {\n    throw new OpacityAttestationError(\n      'AttestationIssuedInFuture',\n      `\\`issuedAt\\` (${session.issuedAt}) is in the future relative to \\`now\\` (${now}). ` +\n        'A post-dated session is rejected permanently, not held until it matures.',\n      { field: 'issuedAt' },\n    );\n  }\n\n  if (now > deadline) {\n    throw new OpacityAttestationError(\n      'AttestationExpired',\n      `The session expired at ${deadline}, before \\`now\\` (${now}).`,\n      { field: 'deadline' },\n    );\n  }\n}\n\n/** Rejects a non-integer / out-of-range chain id before it lands in a signed domain. */\nexport function assertChainId(value: number): number {\n  if (!Number.isInteger(value) || value <= 0) {\n    throw new OpacityAttestationError('MalformedInput', '`chainId` must be a positive integer.', {\n      field: 'chainId',\n    });\n  }\n  return value;\n}\n"]}

package/dist/chunk-3L7NNVUV.cjs

@@ -0,0 +1,184 @@
+'use strict';
+
+var chunkHJQZWNZJ_cjs = require('./chunk-HJQZWNZJ.cjs');
+var viem = require('viem');
+
+// src/documents/constants.ts
+var DOCUMENT_ATTESTOR_DOMAIN_NAME = "DocumentAttestor";
+var DOCUMENT_ATTESTOR_DOMAIN_VERSION = "1";
+var DOCUMENT_ACCEPTANCE_TYPES = {
+  DocumentAcceptance: [
+    { name: "nonce", type: "bytes32" },
+    { name: "docHash", type: "bytes32" },
+    { name: "deadline", type: "uint256" }
+  ]
+};
+var DOCUMENT_ACCEPTANCE_PRIMARY_TYPE = "DocumentAcceptance";
+var EIP712_DOMAIN_TYPE = [
+  { name: "name", type: "string" },
+  { name: "version", type: "string" },
+  { name: "chainId", type: "uint256" },
+  { name: "verifyingContract", type: "address" }
+];
+var DOCUMENT_ACCEPTANCE_TYPEHASH = "0xcd87f8252156623d78fd52f8f4f1c63bcda5d0b21a8c7f56f63a1759103d6598";
+var MAX_ATTESTATION_LIFETIME_SECONDS = 2592000n;
+var ECDSA_SIGNATURE_BYTES = 65;
+
+// src/documents/validate.ts
+var ZERO_BYTES32 = "0x0000000000000000000000000000000000000000000000000000000000000000";
+function assertAddress(value, field) {
+  if (typeof value !== "string" || !viem.isAddress(value, { strict: false })) {
+    throw new chunkHJQZWNZJ_cjs.OpacityAttestationError("MalformedInput", `\`${field}\` is not a valid address.`, {
+      field
+    });
+  }
+  const normalized = viem.getAddress(value);
+  if (normalized === "0x0000000000000000000000000000000000000000") {
+    throw new chunkHJQZWNZJ_cjs.OpacityAttestationError("ZeroAddress", `\`${field}\` must not be the zero address.`, {
+      field
+    });
+  }
+  return normalized;
+}
+function assertBytes32(value, field) {
+  if (typeof value !== "string" || !viem.isHex(value) || value.length !== 2 + 64) {
+    throw new chunkHJQZWNZJ_cjs.OpacityAttestationError(
+      "MalformedInput",
+      `\`${field}\` must be a 32-byte hex string (0x + 64 hex chars).`,
+      { field }
+    );
+  }
+  return value;
+}
+function assertTraitId(value) {
+  const traitId = assertBytes32(value, "traitId");
+  if (traitId.toLowerCase() === ZERO_BYTES32) {
+    throw new chunkHJQZWNZJ_cjs.OpacityAttestationError("InvalidTraitId", "`traitId` must not be zero.", {
+      field: "traitId"
+    });
+  }
+  return traitId;
+}
+function assertBoolean(value, field) {
+  if (typeof value !== "boolean") {
+    throw new chunkHJQZWNZJ_cjs.OpacityAttestationError("MalformedInput", `\`${field}\` must be a boolean.`, {
+      field
+    });
+  }
+  return value;
+}
+function assertDocHash(value) {
+  const docHash = assertBytes32(value, "docHash");
+  if (docHash.toLowerCase() === ZERO_BYTES32) {
+    throw new chunkHJQZWNZJ_cjs.OpacityAttestationError("InvalidDocHash", "`docHash` must not be zero.", {
+      field: "docHash"
+    });
+  }
+  return docHash;
+}
+function assertNonce(value) {
+  return assertBytes32(value, "nonce");
+}
+function assertTimestamp(value, field) {
+  if (typeof value !== "bigint") {
+    throw new chunkHJQZWNZJ_cjs.OpacityAttestationError(
+      "MalformedInput",
+      `\`${field}\` must be a bigint of unix seconds.`,
+      { field }
+    );
+  }
+  if (value < 0n) {
+    throw new chunkHJQZWNZJ_cjs.OpacityAttestationError("MalformedInput", `\`${field}\` must not be negative.`, {
+      field
+    });
+  }
+  return value;
+}
+function assertServerSignature(value) {
+  if (typeof value !== "string" || !viem.isHex(value)) {
+    throw new chunkHJQZWNZJ_cjs.OpacityAttestationError("MalformedInput", "`serverSignature` must be a hex string.", {
+      field: "serverSignature"
+    });
+  }
+  if (value.length !== 2 + ECDSA_SIGNATURE_BYTES * 2) {
+    const length = viem.size(value);
+    throw new chunkHJQZWNZJ_cjs.OpacityAttestationError(
+      "InvalidSignatureLength",
+      `\`serverSignature\` must be ${ECDSA_SIGNATURE_BYTES} bytes; received ${length}. The document server signs with ECDSA, which accepts no other length.`,
+      { field: "serverSignature" }
+    );
+  }
+  return value;
+}
+function assertUserSignature(value) {
+  if (typeof value !== "string" || !viem.isHex(value) || value.length % 2 !== 0) {
+    throw new chunkHJQZWNZJ_cjs.OpacityAttestationError(
+      "MalformedInput",
+      "`userSignature` must be a hex string of whole bytes.",
+      { field: "userSignature" }
+    );
+  }
+  return value;
+}
+function assertSessionWindow(session, options = {}) {
+  const { deadline } = session;
+  assertTimestamp(deadline, "deadline");
+  if (session.issuedAt !== void 0) {
+    const issuedAt = assertTimestamp(session.issuedAt, "issuedAt");
+    const maxAllowed = issuedAt + MAX_ATTESTATION_LIFETIME_SECONDS;
+    if (deadline > maxAllowed) {
+      throw new chunkHJQZWNZJ_cjs.OpacityAttestationError(
+        "AttestationDeadlineTooFar",
+        `\`deadline\` (${deadline}) exceeds \`issuedAt\` + MAX_ATTESTATION_LIFETIME (${maxAllowed}).`,
+        { field: "deadline" }
+      );
+    }
+  }
+  const { now } = options;
+  if (now === void 0) return;
+  assertTimestamp(now, "now");
+  if (session.issuedAt !== void 0 && session.issuedAt > now) {
+    throw new chunkHJQZWNZJ_cjs.OpacityAttestationError(
+      "AttestationIssuedInFuture",
+      `\`issuedAt\` (${session.issuedAt}) is in the future relative to \`now\` (${now}). A post-dated session is rejected permanently, not held until it matures.`,
+      { field: "issuedAt" }
+    );
+  }
+  if (now > deadline) {
+    throw new chunkHJQZWNZJ_cjs.OpacityAttestationError(
+      "AttestationExpired",
+      `The session expired at ${deadline}, before \`now\` (${now}).`,
+      { field: "deadline" }
+    );
+  }
+}
+function assertChainId(value) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new chunkHJQZWNZJ_cjs.OpacityAttestationError("MalformedInput", "`chainId` must be a positive integer.", {
+      field: "chainId"
+    });
+  }
+  return value;
+}
+
+exports.DOCUMENT_ACCEPTANCE_PRIMARY_TYPE = DOCUMENT_ACCEPTANCE_PRIMARY_TYPE;
+exports.DOCUMENT_ACCEPTANCE_TYPEHASH = DOCUMENT_ACCEPTANCE_TYPEHASH;
+exports.DOCUMENT_ACCEPTANCE_TYPES = DOCUMENT_ACCEPTANCE_TYPES;
+exports.DOCUMENT_ATTESTOR_DOMAIN_NAME = DOCUMENT_ATTESTOR_DOMAIN_NAME;
+exports.DOCUMENT_ATTESTOR_DOMAIN_VERSION = DOCUMENT_ATTESTOR_DOMAIN_VERSION;
+exports.ECDSA_SIGNATURE_BYTES = ECDSA_SIGNATURE_BYTES;
+exports.EIP712_DOMAIN_TYPE = EIP712_DOMAIN_TYPE;
+exports.MAX_ATTESTATION_LIFETIME_SECONDS = MAX_ATTESTATION_LIFETIME_SECONDS;
+exports.assertAddress = assertAddress;
+exports.assertBoolean = assertBoolean;
+exports.assertBytes32 = assertBytes32;
+exports.assertChainId = assertChainId;
+exports.assertDocHash = assertDocHash;
+exports.assertNonce = assertNonce;
+exports.assertServerSignature = assertServerSignature;
+exports.assertSessionWindow = assertSessionWindow;
+exports.assertTimestamp = assertTimestamp;
+exports.assertTraitId = assertTraitId;
+exports.assertUserSignature = assertUserSignature;
+//# sourceMappingURL=chunk-3L7NNVUV.cjs.map
+//# sourceMappingURL=chunk-3L7NNVUV.cjs.map

package/dist/chunk-3L7NNVUV.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/documents/constants.ts","../src/documents/validate.ts"],"names":["isAddress","OpacityAttestationError","getAddress","isHex","size"],"mappings":"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","file":"chunk-3L7NNVUV.cjs","sourcesContent":["import type { Hex } from 'viem';\n\n/**\n * EIP-712 domain `name` and `version`, from `EIP712(\"DocumentAttestor\", \"1\")` in\n * `DocumentAttestor.sol`. The domain has no `salt` — OpenZeppelin's `EIP712` uses\n * `EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)`.\n */\nexport const DOCUMENT_ATTESTOR_DOMAIN_NAME = 'DocumentAttestor';\nexport const DOCUMENT_ATTESTOR_DOMAIN_VERSION = '1';\n\n/**\n * The payload the investor's wallet signs.\n *\n * It deliberately binds neither `wallet` nor `traitId`: the trait is an internal mapping and the\n * prompt should show only what the human is agreeing to, while the binding to a wallet comes from\n * ECDSA recovery (or, for ERC-1271, from the server's own signature). Cross-deployment and\n * cross-chain replay are stopped by the domain's `chainId` + `verifyingContract`.\n *\n * Field order is consensus-critical — it is part of the type hash.\n */\nexport const DOCUMENT_ACCEPTANCE_TYPES = {\n  DocumentAcceptance: [\n    { name: 'nonce', type: 'bytes32' },\n    { name: 'docHash', type: 'bytes32' },\n    { name: 'deadline', type: 'uint256' },\n  ],\n} as const;\n\nexport const DOCUMENT_ACCEPTANCE_PRIMARY_TYPE = 'DocumentAcceptance';\n\n/**\n * The EIP-712 domain type, needed only by `toEip712JsonPayload`: raw `eth_signTypedData_v4`\n * requires `EIP712Domain` to be present in `types`, whereas viem derives it and ethers v6 throws\n * if you supply it.\n */\nexport const EIP712_DOMAIN_TYPE = [\n  { name: 'name', type: 'string' },\n  { name: 'version', type: 'string' },\n  { name: 'chainId', type: 'uint256' },\n  { name: 'verifyingContract', type: 'address' },\n] as const;\n\n/**\n * `keccak256(\"DocumentAcceptance(bytes32 nonce,bytes32 docHash,uint256 deadline)\")`.\n *\n * Not used to build the payload (viem derives it from {@link DOCUMENT_ACCEPTANCE_TYPES}); exported\n * so a consumer can assert it against the contract's `DOCUMENT_ACCEPTANCE_TYPEHASH()` getter.\n */\nexport const DOCUMENT_ACCEPTANCE_TYPEHASH: Hex =\n  '0xcd87f8252156623d78fd52f8f4f1c63bcda5d0b21a8c7f56f63a1759103d6598';\n\n/**\n * Mirrors `DocumentAttestor.MAX_ATTESTATION_LIFETIME` (30 days).\n *\n * Duplicated off-chain so `deadline > issuedAt + MAX_ATTESTATION_LIFETIME` can be caught before the\n * investor is prompted, rather than at redemption. It is a `constant` on a non-upgradeable contract,\n * so it cannot drift for a given deployment — but a successor deployment could choose a different\n * value, which is why `MAX_ATTESTATION_LIFETIME` is kept in `documentAttestorAbi` for\n * consumers that want to read it back.\n */\nexport const MAX_ATTESTATION_LIFETIME_SECONDS = 2_592_000n;\n\n/** Length in bytes of the ECDSA signature `ECDSA.recover` accepts — it rejects every other length. */\nexport const ECDSA_SIGNATURE_BYTES = 65;\n","import { getAddress, isAddress, isHex, size } from 'viem';\nimport type { Address, Hex } from 'viem';\n\nimport { OpacityAttestationError } from '../errors.js';\nimport { ECDSA_SIGNATURE_BYTES, MAX_ATTESTATION_LIFETIME_SECONDS } from './constants.js';\nimport type { ClockOptions } from './types.js';\n\nconst ZERO_BYTES32 = '0x0000000000000000000000000000000000000000000000000000000000000000';\n\n/**\n * Normalises an address and rejects the zero address.\n *\n * Returns the checksummed form: `attestDocument` takes `wallet` as a plain `address`, so casing\n * does not affect the calldata, but returning the canonical form keeps the descriptor comparable.\n */\nexport function assertAddress(value: Address, field: string): Address {\n  if (typeof value !== 'string' || !isAddress(value, { strict: false })) {\n    throw new OpacityAttestationError('MalformedInput', `\\`${field}\\` is not a valid address.`, {\n      field,\n    });\n  }\n  const normalized = getAddress(value);\n  if (normalized === '0x0000000000000000000000000000000000000000') {\n    throw new OpacityAttestationError('ZeroAddress', `\\`${field}\\` must not be the zero address.`, {\n      field,\n    });\n  }\n  return normalized;\n}\n\n/**\n * Rejects anything that is not 32 bytes of hex. Zero-ness is checked separately, per field.\n *\n * Length is checked on the string, not via `size()`, which rounds a half-byte up — `0x` followed\n * by 63 hex chars has a `size()` of 32 but is not a valid `bytes32`.\n */\nexport function assertBytes32(value: Hex, field: string): Hex {\n  if (typeof value !== 'string' || !isHex(value) || value.length !== 2 + 64) {\n    throw new OpacityAttestationError(\n      'MalformedInput',\n      `\\`${field}\\` must be a 32-byte hex string (0x + 64 hex chars).`,\n      { field },\n    );\n  }\n  return value;\n}\n\n/**\n * `traitId` must be non-zero — `InvalidTraitId`.\n *\n * A zero trait id is almost always an un-set config value rather than a real trait.\n */\nexport function assertTraitId(value: Hex): Hex {\n  const traitId = assertBytes32(value, 'traitId');\n  if (traitId.toLowerCase() === ZERO_BYTES32) {\n    throw new OpacityAttestationError('InvalidTraitId', '`traitId` must not be zero.', {\n      field: 'traitId',\n    });\n  }\n  return traitId;\n}\n\n/** Strict runtime boolean validation for callers that bypass TypeScript declarations. */\nexport function assertBoolean(value: boolean, field: string): boolean {\n  if (typeof value !== 'boolean') {\n    throw new OpacityAttestationError('MalformedInput', `\\`${field}\\` must be a boolean.`, {\n      field,\n    });\n  }\n  return value;\n}\n\n/**\n * `docHash` must be non-zero — `InvalidDocHash`.\n *\n * No executed document hashes to zero, so a zero here is a server-side bug and must not be attested.\n */\nexport function assertDocHash(value: Hex): Hex {\n  const docHash = assertBytes32(value, 'docHash');\n  if (docHash.toLowerCase() === ZERO_BYTES32) {\n    throw new OpacityAttestationError('InvalidDocHash', '`docHash` must not be zero.', {\n      field: 'docHash',\n    });\n  }\n  return docHash;\n}\n\n/**\n * `nonce` must be well-formed, but may be zero.\n *\n * The contract applies no zero-check to the nonce — slot zero is burnable like any other — so\n * rejecting it here would be stricter than the chain.\n */\nexport function assertNonce(value: Hex): Hex {\n  return assertBytes32(value, 'nonce');\n}\n\n/** Rejects negative or non-`bigint` unix timestamps before they are encoded as `uint256`. */\nexport function assertTimestamp(value: bigint, field: string): bigint {\n  if (typeof value !== 'bigint') {\n    throw new OpacityAttestationError(\n      'MalformedInput',\n      `\\`${field}\\` must be a bigint of unix seconds.`,\n      { field },\n    );\n  }\n  if (value < 0n) {\n    throw new OpacityAttestationError('MalformedInput', `\\`${field}\\` must not be negative.`, {\n      field,\n    });\n  }\n  return value;\n}\n\n/**\n * The 65-byte rule for the SERVER signature only.\n *\n * `ECDSA.recover` accepts exactly one length and reverts `ECDSAInvalidSignatureLength` on any\n * other. The investor signature must NOT be length-checked: `SignatureChecker` routes a\n * code-bearing wallet (a Safe, or an EIP-7702-delegated EOA) to ERC-1271, where the signature is\n * whatever that wallet's own validation logic accepts.\n */\nexport function assertServerSignature(value: Hex): Hex {\n  if (typeof value !== 'string' || !isHex(value)) {\n    throw new OpacityAttestationError('MalformedInput', '`serverSignature` must be a hex string.', {\n      field: 'serverSignature',\n    });\n  }\n  if (value.length !== 2 + ECDSA_SIGNATURE_BYTES * 2) {\n    const length = size(value);\n    throw new OpacityAttestationError(\n      'InvalidSignatureLength',\n      `\\`serverSignature\\` must be ${ECDSA_SIGNATURE_BYTES} bytes; received ${length}. ` +\n        'The document server signs with ECDSA, which accepts no other length.',\n      { field: 'serverSignature' },\n    );\n  }\n  return value;\n}\n\n/**\n * The investor signature: hex, any BYTE length — an ERC-1271 wallet is not 65 bytes.\n *\n * Only the half-byte case is rejected, since it cannot encode as `bytes`.\n */\nexport function assertUserSignature(value: Hex): Hex {\n  if (typeof value !== 'string' || !isHex(value) || value.length % 2 !== 0) {\n    throw new OpacityAttestationError(\n      'MalformedInput',\n      '`userSignature` must be a hex string of whole bytes.',\n      { field: 'userSignature' },\n    );\n  }\n  return value;\n}\n\n/**\n * The session-lifetime rules, split by whether they need a clock.\n *\n * `deadline <= issuedAt + MAX_ATTESTATION_LIFETIME` is absolute and always checked. The two\n * clock-relative rules run only when `now` is supplied — see {@link ClockOptions} for why that is\n * opt-in.\n */\nexport function assertSessionWindow(\n  session: { issuedAt?: bigint | undefined; deadline: bigint },\n  options: ClockOptions = {},\n): void {\n  const { deadline } = session;\n  assertTimestamp(deadline, 'deadline');\n\n  if (session.issuedAt !== undefined) {\n    const issuedAt = assertTimestamp(session.issuedAt, 'issuedAt');\n    const maxAllowed = issuedAt + MAX_ATTESTATION_LIFETIME_SECONDS;\n    if (deadline > maxAllowed) {\n      throw new OpacityAttestationError(\n        'AttestationDeadlineTooFar',\n        `\\`deadline\\` (${deadline}) exceeds \\`issuedAt\\` + MAX_ATTESTATION_LIFETIME (${maxAllowed}).`,\n        { field: 'deadline' },\n      );\n    }\n  }\n\n  const { now } = options;\n  if (now === undefined) return;\n  assertTimestamp(now, 'now');\n\n  if (session.issuedAt !== undefined && session.issuedAt > now) {\n    throw new OpacityAttestationError(\n      'AttestationIssuedInFuture',\n      `\\`issuedAt\\` (${session.issuedAt}) is in the future relative to \\`now\\` (${now}). ` +\n        'A post-dated session is rejected permanently, not held until it matures.',\n      { field: 'issuedAt' },\n    );\n  }\n\n  if (now > deadline) {\n    throw new OpacityAttestationError(\n      'AttestationExpired',\n      `The session expired at ${deadline}, before \\`now\\` (${now}).`,\n      { field: 'deadline' },\n    );\n  }\n}\n\n/** Rejects a non-integer / out-of-range chain id before it lands in a signed domain. */\nexport function assertChainId(value: number): number {\n  if (!Number.isInteger(value) || value <= 0) {\n    throw new OpacityAttestationError('MalformedInput', '`chainId` must be a positive integer.', {\n      field: 'chainId',\n    });\n  }\n  return value;\n}\n"]}

package/dist/chunk-54Q3MU62.js

@@ -0,0 +1,29 @@
+// src/errors.ts
+var OpacityIssuerError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "OpacityIssuerError";
+  }
+};
+var OpacityConfigError = class extends OpacityIssuerError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "OpacityConfigError";
+  }
+};
+var OpacityAttestationError = class extends OpacityIssuerError {
+  /** Which check failed. Mirrors a contract error name where one exists. */
+  code;
+  /** The offending parameter, when the failure is attributable to a single one. */
+  field;
+  constructor(code, message, options) {
+    super(message, options?.cause === void 0 ? void 0 : { cause: options.cause });
+    this.name = "OpacityAttestationError";
+    this.code = code;
+    this.field = options?.field;
+  }
+};
+
+export { OpacityAttestationError, OpacityConfigError, OpacityIssuerError };
+//# sourceMappingURL=chunk-54Q3MU62.js.map
+//# sourceMappingURL=chunk-54Q3MU62.js.map

package/dist/chunk-54Q3MU62.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts"],"names":[],"mappings":";AAmBO,IAAM,kBAAA,GAAN,cAAiC,KAAA,CAAM;AAAA,EAC5C,WAAA,CAAY,SAAiB,OAAA,EAA+B;AAC1D,IAAA,KAAA,CAAM,SAAS,OAAO,CAAA;AACtB,IAAA,IAAA,CAAK,IAAA,GAAO,oBAAA;AAAA,EACd;AACF;AAGO,IAAM,kBAAA,GAAN,cAAiC,kBAAA,CAAmB;AAAA,EACzD,WAAA,CAAY,SAAiB,OAAA,EAA+B;AAC1D,IAAA,KAAA,CAAM,SAAS,OAAO,CAAA;AACtB,IAAA,IAAA,CAAK,IAAA,GAAO,oBAAA;AAAA,EACd;AACF;AASO,IAAM,uBAAA,GAAN,cAAsC,kBAAA,CAAmB;AAAA;AAAA,EAErD,IAAA;AAAA;AAAA,EAEA,KAAA;AAAA,EAET,WAAA,CACE,IAAA,EACA,OAAA,EACA,OAAA,EACA;AACA,IAAA,KAAA,CAAM,OAAA,EAAS,SAAS,KAAA,KAAU,MAAA,GAAY,SAAY,EAAE,KAAA,EAAO,OAAA,CAAQ,KAAA,EAAO,CAAA;AAClF,IAAA,IAAA,CAAK,IAAA,GAAO,yBAAA;AACZ,IAAA,IAAA,CAAK,IAAA,GAAO,IAAA;AACZ,IAAA,IAAA,CAAK,QAAQ,OAAA,EAAS,KAAA;AAAA,EACxB;AACF","file":"chunk-54Q3MU62.js","sourcesContent":["import type { AttestationErrorCode } from './documents/types.js';\n\n// `OpacityDiscoveryError` is deliberately NOT re-exported from here, even though it belongs to\n// this hierarchy and is exported from the package root (via `documents/index.ts`).\n//\n// A value re-export — `export { OpacityDiscoveryError } from './documents/discovery.js'` — is a\n// RUNTIME edge, and `discovery.ts` already imports this module for `OpacityIssuerError`. The cycle\n// is fatal, not benign: `config.ts` imports `errors.js` first, so `errors.js` starts evaluating,\n// the re-export pulls in `discovery.js`, and `class OpacityDiscoveryError extends\n// OpacityIssuerError` runs while `OpacityIssuerError` is still in its temporal dead zone —\n// `TypeError: Class extends value undefined`. Verified, not theorised.\n//\n// The type-only imports above are safe for the opposite reason: `verbatimModuleSyntax` erases\n// them, so they create no runtime edge at all.\n\n/**\n * Base class for every error thrown by this SDK, so consumers can do a single\n * `instanceof OpacityIssuerError` check at their integration boundary.\n */\nexport class OpacityIssuerError extends Error {\n  constructor(message: string, options?: { cause?: unknown }) {\n    super(message, options);\n    this.name = 'OpacityIssuerError';\n  }\n}\n\n/** Thrown when `createOpacityIssuerClient` is called with invalid configuration. */\nexport class OpacityConfigError extends OpacityIssuerError {\n  constructor(message: string, options?: { cause?: unknown }) {\n    super(message, options);\n    this.name = 'OpacityConfigError';\n  }\n}\n\n/**\n * Thrown by the document-attestation builders when a parameter would produce a transaction the\n * `DocumentAttestor` is guaranteed to reject, or is too malformed to encode.\n *\n * Branch on {@link code}, not on the message: each value names the on-chain error it stands in for,\n * so a pre-flight rejection is legible in the same terms as the revert it saved.\n */\nexport class OpacityAttestationError extends OpacityIssuerError {\n  /** Which check failed. Mirrors a contract error name where one exists. */\n  readonly code: AttestationErrorCode;\n  /** The offending parameter, when the failure is attributable to a single one. */\n  readonly field: string | undefined;\n\n  constructor(\n    code: AttestationErrorCode,\n    message: string,\n    options?: { field?: string; cause?: unknown },\n  ) {\n    super(message, options?.cause === undefined ? undefined : { cause: options.cause });\n    this.name = 'OpacityAttestationError';\n    this.code = code;\n    this.field = options?.field;\n  }\n}\n"]}