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.

import { createIssuersNamespace } from 'opacity-issuer-core';
import { createSubgraphClient, createIndexerNamespace } from 'opacity-issuer-core/subgraph';

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 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.

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.

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.