@aromedia/contracts-sdk 0.2.0

package/dist/onboarding-DxL_LpM3.d.ts

@@ -0,0 +1,302 @@
+import { PublicClient, WalletClient, GetContractReturnType, Chain, Transport, Account, Hex } from 'viem';
+import { AroChainId } from './generated/addresses.js';
+import { AroMediaAccessManager_ABI, AroMediaAssetsRegistry_ABI, ForcedTransferManager_ABI, AroMediaIncMultiSig_ABI, AroNomination_ABI, AroMediaRWA_ABI, AroSBT_ABI } from './generated/abis.js';
+
+/** Mirrors AroSBT.Tier. */
+declare enum AroTier {
+    STANDARD = 0,
+    VERIFIED = 1,
+    TRUSTED = 2,
+    FOUNDING = 3
+}
+declare const AroTierLabels: Record<AroTier, string>;
+/** Mirrors AroNomination.NominationStatus. */
+declare enum NominationStatus {
+    NONE = 0,
+    PENDING = 1,
+    APPROVED = 2,
+    CLEARED = 3
+}
+declare const NominationStatusLabels: Record<NominationStatus, string>;
+/** Mirrors ForcedTransferManager.ForcedTransferStatus. */
+declare enum ForcedTransferStatus {
+    PENDING = 0,
+    APPROVED = 1,
+    EXECUTED = 2,
+    CANCELLED = 3
+}
+declare const ForcedTransferStatusLabels: Record<ForcedTransferStatus, string>;
+
+type AroAccessManagerContract = GetContractReturnType<typeof AroMediaAccessManager_ABI, {
+    public: PublicClient;
+    wallet?: WalletClient;
+}>;
+interface AccessManagerClientOpts {
+    address: `0x${string}`;
+    publicClient: PublicClient;
+    walletClient?: WalletClient;
+}
+declare function createAccessManagerClient(opts: AccessManagerClientOpts): AroAccessManagerContract;
+/**
+ * Role IDs as defined in AroMediaAccessManager.sol. Mirroring them here
+ * lets the dapp grant/revoke without re-reading the contract just to know
+ * which uint64 corresponds to which role.
+ */
+declare const AroRoles: {
+    readonly ORG_ADMIN: 0n;
+    readonly PROTOCOL_ADMIN: 1n;
+    readonly TREASURY_CONTROLLER: 2n;
+    readonly MARKET_MAKER: 3n;
+    readonly MINTER: 4n;
+};
+type AroRoleName = keyof typeof AroRoles;
+
+type AroAssetsRegistryContract = GetContractReturnType<typeof AroMediaAssetsRegistry_ABI, {
+    public: PublicClient;
+    wallet?: WalletClient;
+}>;
+interface AssetsRegistryClientOpts {
+    address: `0x${string}`;
+    publicClient: PublicClient;
+    walletClient?: WalletClient;
+}
+declare function createAssetsRegistryClient(opts: AssetsRegistryClientOpts): AroAssetsRegistryContract;
+
+type ForcedTransferManagerContract = GetContractReturnType<typeof ForcedTransferManager_ABI, {
+    public: PublicClient;
+    wallet?: WalletClient;
+}>;
+interface ForcedTransferClientOpts {
+    address: `0x${string}`;
+    publicClient: PublicClient;
+    walletClient?: WalletClient;
+}
+declare function createForcedTransferClient(opts: ForcedTransferClientOpts): ForcedTransferManagerContract;
+
+type AroMultiSigContract = GetContractReturnType<typeof AroMediaIncMultiSig_ABI, {
+    public: PublicClient;
+    wallet?: WalletClient;
+}>;
+interface MultiSigClientOpts {
+    address: `0x${string}`;
+    publicClient: PublicClient;
+    walletClient?: WalletClient;
+}
+declare function createMultiSigClient(opts: MultiSigClientOpts): AroMultiSigContract;
+
+type AroNominationContract = GetContractReturnType<typeof AroNomination_ABI, {
+    public: PublicClient;
+    wallet?: WalletClient;
+}>;
+interface NominationClientOpts {
+    address: `0x${string}`;
+    publicClient: PublicClient;
+    walletClient?: WalletClient;
+}
+declare function createNominationClient(opts: NominationClientOpts): AroNominationContract;
+
+type AroRWAContract = GetContractReturnType<typeof AroMediaRWA_ABI, {
+    public: PublicClient;
+    wallet?: WalletClient;
+}>;
+interface RwaClientOpts {
+    address: `0x${string}`;
+    publicClient: PublicClient;
+    walletClient?: WalletClient;
+}
+declare function createRwaClient(opts: RwaClientOpts): AroRWAContract;
+
+/**
+ * Typed viem contract handle for AroSBT.
+ *
+ * Use `read.hasSBT(address)`, `read.getMemberData(address)`, etc. for views;
+ * `write.mint(...)`, `write.revoke(...)`, etc. for state-changing calls when
+ * a wallet client is bound.
+ */
+type AroSBTContract = GetContractReturnType<typeof AroSBT_ABI, {
+    public: PublicClient;
+    wallet?: WalletClient;
+}>;
+interface SbtClientOpts {
+    address: `0x${string}`;
+    publicClient: PublicClient;
+    walletClient?: WalletClient;
+}
+/**
+ * Bind the AroSBT ABI to its deployed address and the caller's viem
+ * clients. The returned object is a thin proxy — calling `client.read.x`
+ * preserves full type inference from the ABI.
+ */
+declare function createSbtClient(opts: SbtClientOpts): AroSBTContract;
+
+/**
+ * Per-contract address overrides. Useful for:
+ *   • local Hardhat where ignition deployments aren't picked up at build time
+ *   • staging deployments living outside of `ignition/deployments`
+ *   • forked-network testing where contracts are at non-canonical addresses
+ */
+type AroAddressOverrides = Partial<Record<"AroSBT" | "AroNomination" | "AroMediaRWA" | "AroMediaAssetsRegistry" | "AroMediaAccessManager" | "AroMediaIncMultiSig" | "ForcedTransferManager", `0x${string}`>>;
+interface CreateAroSdkOpts {
+    /** Target chain. Must be a chainId the SDK knows about. */
+    chain: Chain & {
+        id: AroChainId;
+    };
+    /** viem transport — defaults to `http()` against the chain's default RPC. */
+    transport?: Transport;
+    /** Optional wallet client for state-changing calls. */
+    walletClient?: WalletClient;
+    /** Override one or more contract addresses (local dev, staging, etc.). */
+    overrides?: AroAddressOverrides;
+}
+interface AroSdk {
+    chainId: AroChainId;
+    publicClient: PublicClient;
+    walletClient?: WalletClient;
+    /** Soulbound identity token. */
+    sbt: AroSBTContract;
+    /** Nomination + vouching workflow. */
+    nomination: AroNominationContract;
+    /** RWA security token (ARO). */
+    rwa: AroRWAContract;
+    /** ERC-721 assets registry. */
+    assetsRegistry: AroAssetsRegistryContract;
+    /** Centralized AccessManager (role grants/revokes). */
+    accessManager: AroAccessManagerContract;
+    /** ERC-7913 multi-sig smart-contract wallet. */
+    multiSig: AroMultiSigContract;
+    /** Regulator-driven forced transfer workflow. */
+    forcedTransfer: ForcedTransferManagerContract;
+    /** Resolve a contract address from the registry (with overrides applied). */
+    addressOf: (name: keyof AroAddressOverrides) => `0x${string}`;
+}
+/**
+ * The single entry point most consumers reach for. Returns a bundle of
+ * typed contract handles bound to a viem PublicClient (and optionally a
+ * WalletClient for writes).
+ *
+ * @example
+ *   const sdk = createAroSdk({
+ *     chain: sepolia as Chain & { id: 11155111 },
+ *     walletClient,
+ *   });
+ *   const isMember = await sdk.sbt.read.hasSBT([userAddress]);
+ *   if (!isMember) await sdk.nomination.write.nominate([userAddress]);
+ */
+declare function createAroSdk(opts: CreateAroSdkOpts): AroSdk;
+/** Helper: peek at the address registry without instantiating an SDK. */
+declare function addressesFor(chainId: AroChainId): Record<keyof AroAddressOverrides, `0x${string}`>;
+
+/**
+ * Onboarding workflow helpers. These wrap multi-call sequences from the
+ * ARO KYC/AML/CFT Policy §6 so the dapp does not have to re-implement the
+ * choreography in three different places.
+ *
+ * Mental model (per Policy §6.3):
+ *
+ *   1. Existing member calls `nominateCandidate(candidate)`.
+ *      The nominator's vouch counts as the first vouch automatically.
+ *
+ *   2. Other existing members call `vouchForCandidate(candidate)`. Each
+ *      vouch increments the count; once `threshold` is reached (3 per
+ *      policy), the nomination moves to APPROVED.
+ *
+ *   3. Off-chain: candidate completes Didit KYC (per MEMO-KYC-PROVIDER).
+ *      Webhook posts back the verification result.
+ *
+ *   4. Compliance Officer reviews and either rejects (`clearNomination`)
+ *      or mints the SBT (`mintSBTForApproved`) with the KYC hash.
+ *
+ *   5. SBT minted → AccessManager grants member roles → access unlocked.
+ *
+ * The write paths use `walletClient.writeContract` directly rather than
+ * the typed contract `.write` namespace. This is intentional: viem
+ * narrows the contract handle's write surface away when the SDK is
+ * instantiated without a walletClient, but workflows are run on demand
+ * after the dapp's wallet connects.
+ */
+interface MembershipStatus {
+    hasSBT: boolean;
+    tier?: AroTier;
+    tokenId?: bigint;
+    memberId?: bigint;
+    issuanceDate?: bigint;
+    kycHash?: `0x${string}`;
+}
+/**
+ * One-call read for the dapp's access-gate page. Returns whether the
+ * connected wallet holds an SBT and, if so, decoded member data.
+ *
+ * Implementation note: reads are issued via `publicClient.readContract`
+ * with the ABI rather than the typed contract instance's `.read`
+ * namespace. viem ≥2.50 narrows `contract.read.*` based on whether a
+ * walletClient was bound at construction time; bypassing that gives us a
+ * stable, version-independent signature.
+ */
+declare function checkMembershipStatus(sdk: AroSdk, account: `0x${string}`): Promise<MembershipStatus>;
+interface NominationSnapshot {
+    status: NominationStatus;
+    nominator: `0x${string}`;
+    vouchers: readonly `0x${string}`[];
+    nominatedAt: bigint;
+    voucherCount: number;
+    threshold: number;
+    remaining: number;
+    ready: boolean;
+}
+/**
+ * Snapshot of the candidate's progress through the vouch flow. The dapp
+ * shows this as "you need N more vouches" in the onboarding UI.
+ */
+declare function getNominationSnapshot(sdk: AroSdk, candidate: `0x${string}`): Promise<NominationSnapshot>;
+/**
+ * Send `nominate(candidate)` from the connected wallet. The contract
+ * gates this behind "caller must already be an SBT holder"; we surface
+ * the right user-facing message via `AroContractError`.
+ */
+declare function nominateCandidate(sdk: AroSdk, candidate: `0x${string}`, opts?: {
+    account?: Account | `0x${string}`;
+}): Promise<Hex>;
+declare function vouchForCandidate(sdk: AroSdk, candidate: `0x${string}`, opts?: {
+    account?: Account | `0x${string}`;
+}): Promise<Hex>;
+/**
+ * Admin path: clear (reject) a nomination. Restricted to authorized roles
+ * via AccessManager; will revert with AccessManagedUnauthorized if the
+ * caller lacks the role.
+ */
+declare function clearNomination(sdk: AroSdk, candidate: `0x${string}`, opts?: {
+    account?: Account | `0x${string}`;
+}): Promise<Hex>;
+interface MintSBTOpts {
+    to: `0x${string}`;
+    /** keccak256 of the verified KYC payload — see utils/kycHash.ts. */
+    kycHash: `0x${string}`;
+    /** Off-chain profile metadata URI (ipfs://... or https://...). */
+    metadataURI: string;
+    /** Initial tier (defaults to STANDARD per Policy §6.1). */
+    tier?: AroTier;
+    account?: Account | `0x${string}`;
+}
+/**
+ * Admin-only: mint the SBT for an approved candidate. The contract gates
+ * this behind ROLE_MINTER via AccessManager (per AroMediaAccessManager).
+ *
+ * Calls the 4-arg mint overload explicitly so the tier is always
+ * specified — the 3-arg overload silently defaults to STANDARD, which
+ * we don't want callers to rely on implicitly.
+ */
+declare function mintSBTForApproved(sdk: AroSdk, opts: MintSBTOpts): Promise<Hex>;
+/**
+ * Convenience: enumerate the policy-derived next action for a wallet so
+ * the onboarding UI can render the correct step (Connect → Nominate →
+ * Vouch → KYC → Mint).
+ */
+type OnboardingStep = "needs-wallet" | "needs-nomination" | "needs-vouches" | "needs-kyc" | "needs-admin-mint" | "member";
+interface OnboardingState {
+    step: OnboardingStep;
+    membership: MembershipStatus;
+    nomination?: NominationSnapshot;
+}
+declare function describeOnboardingState(sdk: AroSdk, wallet: `0x${string}` | undefined): Promise<OnboardingState>;
+
+export { type AccessManagerClientOpts as A, createAroSdk as B, type CreateAroSdkOpts as C, createAssetsRegistryClient as D, createForcedTransferClient as E, type ForcedTransferClientOpts as F, createMultiSigClient as G, createNominationClient as H, createRwaClient as I, createSbtClient as J, describeOnboardingState as K, getNominationSnapshot as L, type MembershipStatus as M, type NominationClientOpts as N, type OnboardingState as O, mintSBTForApproved as P, nominateCandidate as Q, type RwaClientOpts as R, type SbtClientOpts as S, vouchForCandidate as T, type AroAccessManagerContract as a, type AroAddressOverrides as b, type AroAssetsRegistryContract as c, type AroMultiSigContract as d, type AroNominationContract as e, type AroRWAContract as f, type AroRoleName as g, AroRoles as h, type AroSBTContract as i, type AroSdk as j, AroTier as k, AroTierLabels as l, type AssetsRegistryClientOpts as m, type ForcedTransferManagerContract as n, ForcedTransferStatus as o, ForcedTransferStatusLabels as p, type MintSBTOpts as q, type MultiSigClientOpts as r, type NominationSnapshot as s, NominationStatus as t, NominationStatusLabels as u, type OnboardingStep as v, addressesFor as w, checkMembershipStatus as x, clearNomination as y, createAccessManagerClient as z };