opacity-issuer-core 0.2.2 → 0.3.0

package/README.md

@@ -6,13 +6,23 @@ Backend-independent Opacity protocol helpers, contract ABIs, policy builders, is
 import { createIssuersNamespace } from 'opacity-issuer-core';
 import { createSubgraphClient, createIndexerNamespace } from 'opacity-issuer-core/subgraph';
 
-const issuers = createIssuersNamespace({ chainId, publicClient, walletClient });
+const indexer = createIndexerNamespace({ url: process.env.SUBGRAPH_URL! });
+const issuers = createIssuersNamespace({ chainId, publicClient, walletClient, indexer });
+const { deployment, policies } = await issuers.discoverDeployment();
 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 });
 ```
 
+Version 0.3.0 adds read-only issuer deployment discovery: indexed evidence selects the protocol,
+RPC verifies its current factory and registries, and the registry's owner-selected contract
+operator identifies its policy engine and approved policy catalog. No copied address manifest or
+existing asset owned by the new issuer is needed. Unsupported governance wiring (including an EOA
+operator), stale data and ambiguous factories fail closed, without a static-address fallback.
+Discovery neither upgrades contracts nor grants issuer roles; prepare and explicitly send each
+registration/deployment action separately. See the
+[issuer lifecycle guide](https://github.com/OpacityLabs/opacity-issuer-sdk/blob/main/docs/issuer-lifecycle.md).
+
 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.

package/dist/index-B8xCRZt1.d.cts

@@ -0,0 +1,452 @@
+import { A as AttestationErrorCode } from './types-B4Yi7WA4.cjs';
+import { Hex, Address } from 'viem';
+
+/**
+ * Base class for every error thrown by this SDK, so consumers can do a single
+ * `instanceof OpacityIssuerError` check at their integration boundary.
+ */
+declare class OpacityIssuerError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown when `createOpacityIssuerClient` is called with invalid configuration. */
+declare class OpacityConfigError extends OpacityIssuerError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown by the document-attestation builders when a parameter would produce a transaction the
+ * `DocumentAttestor` is guaranteed to reject, or is too malformed to encode.
+ *
+ * Branch on {@link code}, not on the message: each value names the on-chain error it stands in for,
+ * so a pre-flight rejection is legible in the same terms as the revert it saved.
+ */
+declare class OpacityAttestationError extends OpacityIssuerError {
+    /** Which check failed. Mirrors a contract error name where one exists. */
+    readonly code: AttestationErrorCode;
+    /** The offending parameter, when the failure is attributable to a single one. */
+    readonly field: string | undefined;
+    constructor(code: AttestationErrorCode, message: string, options?: {
+        field?: string;
+        cause?: unknown;
+    });
+}
+
+/** Minimal fetch interface shared by direct transports. */
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+interface Field<T> {
+    selection?: string;
+    parse(value: unknown, path: string, domain?: boolean): T;
+}
+type Parsed<T> = T extends Field<infer V> ? V : never;
+declare const userRef: Field<{
+    id: `0x${string}`;
+}>;
+declare const metaField: Field<{
+    deployment: string;
+    hasIndexingErrors: boolean;
+    block: {
+        number: bigint;
+        hash: `0x${string}` | null;
+        timestamp: bigint | null;
+    };
+}>;
+declare const tokenField: Field<{
+    id: `0x${string}`;
+    issuer: {
+        id: `0x${string}`;
+    };
+    issuerAdmin: `0x${string}` | null;
+    allowlistRegistry: `0x${string}`;
+    name: string | null;
+    symbol: string | null;
+    paused: boolean;
+    mintingPaused: boolean;
+    policyEngine: `0x${string}` | null;
+    transferOperator: `0x${string}` | null;
+    tokenTraitRegistry: `0x${string}` | null;
+    maxPolicies: bigint | null;
+    activePolicyCount: bigint;
+    activeRuleSetSnapshot: `0x${string}` | null;
+    ruleSetDeploymentCount: bigint;
+    deployedAtBlock: bigint;
+    deployedAtTimestamp: bigint;
+    deployTxHash: `0x${string}`;
+    beaconVariant: {
+        id: `0x${string}`;
+        beacon: `0x${string}`;
+        isActive: boolean;
+    } | null;
+}>;
+declare const supplyField: Field<{
+    id: `0x${string}`;
+    token: {
+        id: `0x${string}`;
+    };
+    tokenId: bigint;
+    totalSupply: bigint;
+    maxSupply: bigint;
+    holderCount: bigint;
+}>;
+declare const policyField: Field<{
+    id: `0x${string}`;
+    token: {
+        id: `0x${string}`;
+    };
+    implementation: {
+        id: `0x${string}`;
+        status: "UNKNOWN" | "PENDING" | "APPROVED" | "REVOKED" | "CANCELLED";
+    };
+    policyType: "TRADING_DISABLED_V1" | "ALLOWED_TRANSFEREE_V1" | "HOLDER_COUNT_CAP_V1" | "FLOOR_BALANCE_V1" | "CEILING_BALANCE_V1" | "DENYLIST_V1" | "INSIDER_FREEZE_V1" | "SELF_TRANSFER_ONLY_V1" | "UNKNOWN";
+    scopeKey: `0x${string}`;
+    active: boolean;
+    rawConfig: `0x${string}`;
+    guardTrait: `0x${string}`;
+    guardMode: "NONE" | "ONLY_IF_FROM_HAS" | "ONLY_IF_TO_HAS" | "ONLY_IF_EITHER_HAS";
+    guardTraitIsGlobal: boolean;
+    configEnabled: boolean | null;
+    configMaxHolders: bigint | null;
+    configIsPercentage: boolean | null;
+    configCeiling: bigint | null;
+    configDenominatorMode: "CURRENT_SUPPLY" | "MAX_SUPPLY" | null;
+    configTraitList: `0x${string}`[] | null;
+    configRequireAll: boolean | null;
+    attachedAtBlock: bigint;
+    lastReconfiguredAtBlock: bigint | null;
+}>;
+declare const entryField: Field<{
+    id: `0x${string}`;
+    status: "VERIFIED" | "COMPLIANCE_REMOVAL" | "USER_REMOVAL" | "MIGRATED";
+    user: {
+        id: `0x${string}`;
+    } | null;
+    expiresAt: bigint | null;
+    addedBy: `0x${string}` | null;
+    migratedTo: `0x${string}` | null;
+    migratedFrom: `0x${string}` | null;
+    lastUpdatedBlock: bigint;
+    lastUpdatedTimestamp: bigint;
+}>;
+declare const accountField: Field<{
+    id: `0x${string}`;
+    isAuthorizedIssuer: boolean;
+    allowlistEntry: {
+        id: `0x${string}`;
+        status: "VERIFIED" | "COMPLIANCE_REMOVAL" | "USER_REMOVAL" | "MIGRATED";
+        user: {
+            id: `0x${string}`;
+        } | null;
+        expiresAt: bigint | null;
+        addedBy: `0x${string}` | null;
+        migratedTo: `0x${string}` | null;
+        migratedFrom: `0x${string}` | null;
+        lastUpdatedBlock: bigint;
+        lastUpdatedTimestamp: bigint;
+    } | null;
+}>;
+declare const globalTraitField: Field<{
+    id: `0x${string}`;
+    user: {
+        id: `0x${string}`;
+    };
+    traitId: `0x${string}`;
+    enabled: boolean;
+    lastUpdatedBy: `0x${string}`;
+    lastUpdatedBlock: bigint;
+    lastUpdatedTimestamp: bigint;
+    traitConfig: {
+        expiryDuration: bigint;
+        teeEnableable: boolean;
+        writerEnableable: boolean;
+    };
+}>;
+declare const tokenTraitField: Field<{
+    id: `0x${string}`;
+    token: {
+        id: `0x${string}`;
+    };
+    user: {
+        id: `0x${string}`;
+    };
+    traitId: `0x${string}`;
+    enabled: boolean;
+    lastUpdatedBlock: bigint;
+    lastUpdatedTimestamp: bigint;
+}>;
+declare const walletBalanceField: Field<{
+    id: `0x${string}`;
+    token: {
+        id: `0x${string}`;
+    };
+    account: {
+        id: `0x${string}`;
+    };
+    tokenId: bigint;
+    balance: bigint;
+    frozenAmount: bigint;
+}>;
+declare const userBalanceField: Field<{
+    id: `0x${string}`;
+    token: {
+        id: `0x${string}`;
+    };
+    user: {
+        id: `0x${string}`;
+    };
+    tokenId: bigint;
+    balance: bigint;
+    openIntervalId: `0x${string}` | null;
+}>;
+declare const transferField: Field<{
+    id: `0x${string}`;
+    token: {
+        id: `0x${string}`;
+    };
+    operator: `0x${string}`;
+    from: {
+        id: `0x${string}`;
+    };
+    to: {
+        id: `0x${string}`;
+    };
+    tokenId: bigint;
+    value: bigint;
+    isBatch: boolean;
+    batchIndex: bigint;
+    blockNumber: bigint;
+    blockTimestamp: bigint;
+    transactionHash: `0x${string}`;
+    logIndex: bigint;
+}>;
+declare const attestationField: Field<{
+    id: `0x${string}`;
+    attestor: {
+        id: `0x${string}`;
+    };
+    document: {
+        id: `0x${string}`;
+    };
+    user: {
+        id: `0x${string}`;
+    };
+    wallet: `0x${string}`;
+    traitId: `0x${string}`;
+    docHash: `0x${string}`;
+    nonce: `0x${string}`;
+    globalTrait: {
+        id: `0x${string}`;
+        enabled: boolean;
+    };
+    blockNumber: bigint;
+    blockTimestamp: bigint;
+    transactionHash: `0x${string}`;
+    logIndex: bigint;
+}>;
+declare const registryField: Field<{
+    id: string;
+    contractAddress: `0x${string}`;
+    paused: boolean;
+    defaultExpiryDuration: bigint | null;
+    authorizedSigner: `0x${string}` | null;
+    teeTraitAllowlistEnforced: boolean;
+}>;
+declare const uriField: Field<{
+    id: `0x${string}`;
+    token: {
+        id: `0x${string}`;
+    };
+    tokenId: bigint;
+    uri: string;
+    lastUpdatedBlock: bigint;
+}>;
+declare const vaultField: Field<{
+    id: `0x${string}`;
+    token: {
+        id: `0x${string}`;
+    };
+    tokenId: bigint;
+    stablecoin: `0x${string}`;
+    firstObservedAtBlock: bigint;
+    firstObservedAtTimestamp: bigint;
+    firstObservedTxHash: `0x${string}`;
+    depositCount: bigint;
+    withdrawalCount: bigint;
+    totalDeposited: bigint;
+    totalWithdrawn: bigint;
+    adminExecutionCount: bigint;
+}>;
+declare const vaultMovementField: Field<{
+    user: {
+        id: `0x${string}`;
+    };
+    amount: bigint;
+    id: `0x${string}`;
+    vault: {
+        id: `0x${string}`;
+    };
+    token: {
+        id: `0x${string}`;
+    };
+    blockNumber: bigint;
+    blockTimestamp: bigint;
+    transactionHash: `0x${string}`;
+}>;
+declare const vaultAdminField: Field<{
+    owner: `0x${string}`;
+    target: `0x${string}`;
+    selector: `0x${string}`;
+    id: `0x${string}`;
+    vault: {
+        id: `0x${string}`;
+    };
+    token: {
+        id: `0x${string}`;
+    };
+    blockNumber: bigint;
+    blockTimestamp: bigint;
+    transactionHash: `0x${string}`;
+}>;
+type IndexerMetadata = Parsed<typeof metaField>;
+type IndexedToken = Parsed<typeof tokenField>;
+type IndexedTokenId = Parsed<typeof supplyField>;
+type IndexedPolicy = Parsed<typeof policyField>;
+type IndexedAccount = Parsed<typeof accountField>;
+type IndexedUser = Parsed<typeof userRef>;
+type IndexedAllowlistEntry = Parsed<typeof entryField>;
+type IndexedGlobalTrait = Parsed<typeof globalTraitField>;
+type IndexedTokenTrait = Parsed<typeof tokenTraitField>;
+type IndexedWalletBalance = Parsed<typeof walletBalanceField>;
+type IndexedUserBalance = Parsed<typeof userBalanceField>;
+type IndexedBalance = IndexedWalletBalance | IndexedUserBalance;
+type IndexedTransfer = Parsed<typeof transferField>;
+type IndexedDocumentAttestation = Parsed<typeof attestationField>;
+type IndexedRegistry = Parsed<typeof registryField>;
+type IndexedTokenURI = Parsed<typeof uriField>;
+/** Event totals are historical activity, not current reserves or redemption liquidity. */
+type IndexedVault = Parsed<typeof vaultField>;
+type IndexedVaultMovement = Parsed<typeof vaultMovementField>;
+type IndexedVaultAdminExecution = Parsed<typeof vaultAdminField>;
+interface IndexerRequestOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    /** Indexed historical state; Graph Node may prune old blocks. Omit to read its current head. */
+    blockNumber?: bigint;
+    /** Prefer a block hash from getMetadata() to keep a snapshot stable across chain reorgs. */
+    blockHash?: Hex;
+}
+/** Opaque to consumers: reuse unchanged with the same method and filters. */
+interface IndexerCursor {
+    after: Hex;
+    blockNumber: bigint;
+    /** Null when Graph Node did not expose the historical block hash. */
+    blockHash: Hex | null;
+    deployment: string;
+    scope: string;
+}
+interface IndexerPageOptions extends IndexerRequestOptions {
+    /** Default 100; integer 1–999. A further row is fetched to detect continuation. */
+    pageSize?: number;
+    cursor?: IndexerCursor;
+}
+interface IndexedResult<T> {
+    item: T | null;
+    meta: IndexerMetadata;
+}
+interface IndexedPage<T> {
+    items: T[];
+    meta: IndexerMetadata;
+    nextCursor: IndexerCursor | null;
+}
+interface ListIndexedTokensParams extends IndexerPageOptions {
+    issuer?: Address;
+    registry?: Address;
+}
+interface TokenIndexPageParams extends IndexerPageOptions {
+    token: Address;
+}
+interface ListIndexedPoliciesParams extends TokenIndexPageParams {
+    /** Defaults to true. Pass false for detached policies. */
+    active?: boolean;
+}
+interface UserIndexPageParams extends IndexerPageOptions {
+    userId: Hex;
+}
+interface ListIndexedTokenTraitsParams extends UserIndexPageParams {
+    token?: Address;
+}
+interface ListIndexedBalancesParams extends IndexerPageOptions {
+    /** Mutually exclusive with userId. Without either filter, lists wallet balances. */
+    wallet?: Address;
+    userId?: Hex;
+    token?: Address;
+    tokenId?: bigint;
+    /** Defaults to true; false also includes zero balances. */
+    positiveOnly?: boolean;
+}
+interface ListIndexedTransfersParams extends IndexerPageOptions {
+    wallet?: Address;
+    token?: Address;
+    tokenId?: bigint;
+}
+interface ListIndexedDocumentAttestationsParams extends IndexerPageOptions {
+    wallet?: Address;
+    userId?: Hex;
+    traitId?: Hex;
+}
+interface ListIndexedVaultsParams extends IndexerPageOptions {
+    token?: Address;
+}
+interface ListIndexedVaultMovementsParams extends ListIndexedVaultsParams {
+    vault?: Address;
+    wallet?: Address;
+}
+interface ListIndexedVaultAdminExecutionsParams extends ListIndexedVaultsParams {
+    vault?: Address;
+    owner?: Address;
+    target?: Address;
+}
+/**
+ * Event-indexed views, not transaction preflight or live balances. The endpoint defines the
+ * indexed chain/registry; Graph metadata identifies a deployment, not a chain id. Verify that
+ * deployment and token.allowlistRegistry against your intended contract environment.
+ *
+ * Arrays are separate paged queries so traits, token IDs and histories cannot truncate silently.
+ * getUser supplies the identity row; use listUserAccounts/listGlobalTraits/listTokenTraits to
+ * traverse it. A historical attestation does not establish a currently enabled trait.
+ */
+interface OpacityIndexerNamespace {
+    getMetadata(options?: IndexerRequestOptions): Promise<IndexerMetadata>;
+    getRegistry(options?: IndexerRequestOptions): Promise<IndexedResult<IndexedRegistry>>;
+    listTokens(params?: ListIndexedTokensParams): Promise<IndexedPage<IndexedToken>>;
+    getToken(token: Address, options?: IndexerRequestOptions): Promise<IndexedResult<IndexedToken>>;
+    listTokenIds(params: TokenIndexPageParams): Promise<IndexedPage<IndexedTokenId>>;
+    listTokenURIs(params: TokenIndexPageParams): Promise<IndexedPage<IndexedTokenURI>>;
+    listPolicies(params: ListIndexedPoliciesParams): Promise<IndexedPage<IndexedPolicy>>;
+    getAccount(wallet: Address, options?: IndexerRequestOptions): Promise<IndexedResult<IndexedAccount>>;
+    getUser(userId: Hex, options?: IndexerRequestOptions): Promise<IndexedResult<IndexedUser>>;
+    listUserAccounts(params: UserIndexPageParams): Promise<IndexedPage<IndexedAllowlistEntry>>;
+    listGlobalTraits(params: UserIndexPageParams): Promise<IndexedPage<IndexedGlobalTrait>>;
+    listTokenTraits(params: ListIndexedTokenTraitsParams): Promise<IndexedPage<IndexedTokenTrait>>;
+    listBalances(params?: ListIndexedBalancesParams): Promise<IndexedPage<IndexedBalance>>;
+    listTransfers(params?: ListIndexedTransfersParams): Promise<IndexedPage<IndexedTransfer>>;
+    listDocumentAttestations(params?: ListIndexedDocumentAttestationsParams): Promise<IndexedPage<IndexedDocumentAttestation>>;
+    /** Requires the sandbox v3 subgraph schema; includes previously assigned vaults. */
+    getVault(vault: Address, options?: IndexerRequestOptions): Promise<IndexedResult<IndexedVault>>;
+    listVaults(params?: ListIndexedVaultsParams): Promise<IndexedPage<IndexedVault>>;
+    listVaultDeposits(params?: ListIndexedVaultMovementsParams): Promise<IndexedPage<IndexedVaultMovement>>;
+    listVaultWithdrawals(params?: ListIndexedVaultMovementsParams): Promise<IndexedPage<IndexedVaultMovement>>;
+    listVaultAdminExecutions(params?: ListIndexedVaultAdminExecutionsParams): Promise<IndexedPage<IndexedVaultAdminExecution>>;
+}
+/** Separate unauthenticated transport: mobile-api headers and wallet auth never enter this factory. */
+declare function createIndexerNamespace(config: {
+    url?: string | undefined;
+    fetch?: FetchLike;
+    timeoutMs?: number;
+}): OpacityIndexerNamespace;
+/** Validate API-decoded domain values with the same schemas used for direct GraphQL data. */
+declare function validateIndexerOperationResult(operation: keyof OpacityIndexerNamespace, value: unknown, args?: readonly unknown[]): unknown;
+
+export { type ListIndexedTokenTraitsParams as A, type ListIndexedTokensParams as B, type ListIndexedTransfersParams as C, type ListIndexedVaultAdminExecutionsParams as D, type ListIndexedVaultMovementsParams as E, type FetchLike as F, type ListIndexedVaultsParams as G, createIndexerNamespace as H, type IndexedAccount as I, validateIndexerOperationResult as J, OpacityAttestationError as K, type ListIndexedBalancesParams as L, OpacityConfigError as M, OpacityIssuerError as O, type TokenIndexPageParams as T, type UserIndexPageParams as U, type OpacityIndexerNamespace as a, type IndexedAllowlistEntry as b, type IndexedBalance as c, type IndexedDocumentAttestation as d, type IndexedGlobalTrait as e, type IndexedPage as f, type IndexedPolicy as g, type IndexedRegistry as h, type IndexedResult as i, type IndexedToken as j, type IndexedTokenId as k, type IndexedTokenTrait as l, type IndexedTokenURI as m, type IndexedTransfer as n, type IndexedUser as o, type IndexedUserBalance as p, type IndexedVault as q, type IndexedVaultAdminExecution as r, type IndexedVaultMovement as s, type IndexedWalletBalance as t, type IndexerCursor as u, type IndexerMetadata as v, type IndexerPageOptions as w, type IndexerRequestOptions as x, type ListIndexedDocumentAttestationsParams as y, type ListIndexedPoliciesParams as z };