@tbookdev/vault-sdk-sui 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,226 @@
+import { SuiClient } from '@mysten/sui/client';
+
+/**
+ * Sui vault registry — contract object ids per network.
+ *
+ * Source of truth: tokenized-asset-claim-portal deployments (mirrored in
+ * tbook-vault-fe/lib/contracts.ts and verified against the Kotlin backend's
+ * authoritative list). Object ids are stable across package upgrades on Sui;
+ * PACKAGE_ID changes on upgrade — keep in sync with DEPLOYMENTS notes.
+ */
+type SuiNetwork = "mainnet" | "testnet";
+interface SuiVaultConfig {
+    /** Catalog vault id (matches the API catalog). */
+    id: string;
+    network: SuiNetwork;
+    packageId: string;
+    usdcType: string;
+    rcusdpType: string;
+    vaultObjectId: string;
+    pendingDepositsId: string;
+    pendingRedeemsId: string;
+    balancesId: string;
+    claimsId: string;
+    userRecordsId: string;
+    vaultTypeConfigId: string;
+    depositSettlementStateId: string;
+}
+declare const USDC_DECIMALS = 6;
+declare const SHARE_DECIMALS = 6;
+declare function getSuiVaultConfig(vaultId: string, network: SuiNetwork): SuiVaultConfig;
+declare function listSuiVaults(network: SuiNetwork): SuiVaultConfig[];
+type SuiVaultErrorCode = "UNKNOWN_VAULT" | "INSUFFICIENT_BALANCE" | "NOTHING_CLAIMABLE" | "RPC_ERROR";
+declare class SuiVaultError extends Error {
+    readonly code: SuiVaultErrorCode;
+    constructor(code: SuiVaultErrorCode, message: string);
+}
+
+/**
+ * Unsigned PTB builders for the rcUSDP Sui vault (vault_api module).
+ *
+ * Ported from tbook-vault-fe/hooks/use-vault-actions.ts, stripped of React
+ * and signing — every builder returns base64 tx bytes for the caller's
+ * wallet infrastructure (WaaS, multisig, CLI) to sign and submit.
+ *
+ * Gas: `tx.build()` selects gas coins owned by `sender`; the sender needs
+ * SUI for gas. Sponsored transactions are a later iteration.
+ */
+
+interface SuiBuildResult {
+    /** Unsigned transaction bytes, base64 — contract format `sui:tx-bytes-base64`. */
+    txBytesBase64: string;
+    /** Human-readable description of what the transaction does. */
+    message: string;
+}
+/** Deposit USDC into the vault (T+1 settlement). `amount` in raw units (1e6). */
+declare function buildDepositTx(client: SuiClient, cfg: SuiVaultConfig, params: {
+    sender: string;
+    amount: bigint;
+}): Promise<SuiBuildResult>;
+/** Queue a redemption for USDC (settles with the next cycle). `shares` raw (1e6). */
+declare function buildQueueRedeemTx(client: SuiClient, cfg: SuiVaultConfig, params: {
+    sender: string;
+    shares: bigint;
+}): Promise<SuiBuildResult>;
+/** Instant redemption to USDC (immediate, higher fee). `shares` raw (1e6). */
+declare function buildInstantRedeemTx(client: SuiClient, cfg: SuiVaultConfig, params: {
+    sender: string;
+    shares: bigint;
+}): Promise<SuiBuildResult>;
+/** Cancel a pending deposit by record id (only while its cycle is accepting). */
+declare function buildCancelDepositTx(client: SuiClient, cfg: SuiVaultConfig, params: {
+    sender: string;
+    recordId: string | bigint;
+}): Promise<SuiBuildResult>;
+/**
+ * Plain USDC transfer (treasury withdrawals to allowlisted addresses).
+ * `amount` in raw units (1e6).
+ */
+declare function buildTransferUsdcTx(client: SuiClient, cfg: SuiVaultConfig, params: {
+    sender: string;
+    recipient: string;
+    amount: bigint;
+}): Promise<SuiBuildResult>;
+/**
+ * Claim settled redemption proceeds. Claims the full claimable balance by
+ * default (contract semantics: claim pays the account's own wallet).
+ * Throws NOTHING_CLAIMABLE when the claimable balance is zero.
+ */
+declare function buildClaimTx(client: SuiClient, cfg: SuiVaultConfig, params: {
+    sender: string;
+    amount?: bigint;
+}): Promise<SuiBuildResult>;
+
+/**
+ * Read queries for the rcUSDP Sui vault.
+ *
+ * Position reads use a single devInspect batch over the vault module's view
+ * functions (ported from tbook-vault-fe/hooks/use-vault-user.ts); vault
+ * state reads the shared Vault object's fields.
+ */
+
+interface SuiVaultPosition {
+    /** Settled shares (1e6). */
+    shares: bigint;
+    /** USDC pending in the current deposit cycle (1e6). */
+    pendingDeposit: bigint;
+    /** Shares queued for redemption (1e6). */
+    pendingRedeem: bigint;
+    /** Settled USDC awaiting claim (1e6). */
+    claimable: bigint;
+}
+interface SuiVaultState {
+    paused: boolean;
+    totalShares: bigint;
+    sharePrice1e18: bigint;
+    depositFeeBps: number;
+    redeemFeeBps: number;
+    raw: Record<string, unknown>;
+}
+/** Fetch a user's full position in one devInspect round-trip. */
+declare function getUserPosition(client: SuiClient, cfg: SuiVaultConfig, address: string): Promise<SuiVaultPosition>;
+/** Read the shared Vault object's state fields. */
+declare function getVaultState(client: SuiClient, cfg: SuiVaultConfig): Promise<SuiVaultState>;
+
+/**
+ * Per-user record reads (UserRecords table) — devInspect over
+ * vault::get_all_user_records, BCS layout ported from
+ * tbook-vault-fe/hooks/use-transaction-history.ts.
+ */
+
+/** Action codes from vault.move. */
+declare const SUI_ACTION: {
+    readonly DEPOSIT: 0;
+    readonly REDEEM: 1;
+    readonly CLAIM: 2;
+    readonly INSTANT_REDEEM: 3;
+    readonly WITHDRAW_RCUSDP: 4;
+    readonly CANCEL_DEPOSIT: 5;
+};
+/** Record status codes from vault.move. */
+declare const SUI_RECORD_STATUS: {
+    readonly PENDING: 0;
+    readonly COMPLETED: 1;
+    readonly CANCELLED: 2;
+};
+interface SuiUserRecord {
+    recordId: string;
+    action: number;
+    /** Raw units (1e6). */
+    amount: bigint;
+    fee: bigint;
+    shares: bigint;
+    status: number;
+    /** Unix ms. */
+    createdAt: number;
+    /** Unix ms; 0 while pending. */
+    settledAt: number;
+    relatedRecordId: string;
+}
+/** Fetch all of a user's vault records, newest first. */
+declare function getUserRecords(client: SuiClient, cfg: SuiVaultConfig, address: string): Promise<SuiUserRecord[]>;
+
+/**
+ * AlphaVault (XAUa tokenized gold) — Sui direct rail builders and reads.
+ *
+ * Contract: rwa-alpha-token `alpha_vault` module. Subscription/redemption
+ * are request-based with T+3 issuer settlement; all user entries take the
+ * single shared AlphaVault object + Clock. Wallets must be whitelisted by
+ * the issuer before subscribing (contract `not_whitelisted` semantics).
+ *
+ * XAUA has 6 decimals (shares are u128 in the same scale); USDC is 1e6.
+ */
+
+interface AlphaVaultConfig {
+    /** Catalog vault id ("xaua-sui"). */
+    id: string;
+    network: "mainnet" | "testnet";
+    packageId: string;
+    vaultObjectId: string;
+    usdcType: string;
+    xauaType: string;
+}
+declare function getAlphaVaultConfig(vaultId: string, network: "mainnet" | "testnet"): AlphaVaultConfig;
+interface AlphaPosition {
+    /** XAUA shares free to redeem (1e6 scale, u128 on-chain). */
+    availableShares: bigint;
+    /** Shares locked in pending redemption requests. */
+    lockedShares: bigint;
+    /** Settled USDC awaiting claim (1e6). */
+    claimableUsdc: bigint;
+    totalSubscribedUsdc: bigint;
+    totalRedeemedShares: bigint;
+    totalClaimedUsdc: bigint;
+}
+interface BuildResult {
+    txBytesBase64: string;
+    message: string;
+}
+/** Subscribe USDC for XAUa at the settlement cycle's NAV (T+3). */
+declare function buildSubscribeTx(client: SuiClient, cfg: AlphaVaultConfig, params: {
+    sender: string;
+    amount: bigint;
+}): Promise<BuildResult>;
+/** Queue a redemption of XAUa shares (T+3 issuer settlement). */
+declare function buildRequestRedemptionTx(client: SuiClient, cfg: AlphaVaultConfig, params: {
+    sender: string;
+    shares: bigint;
+}): Promise<BuildResult>;
+/** Cancel a pending subscription or redemption request by id. */
+declare function buildCancelRequestTx(client: SuiClient, cfg: AlphaVaultConfig, params: {
+    sender: string;
+    requestId: string | bigint;
+    kind: "subscription" | "redemption";
+}): Promise<BuildResult>;
+/**
+ * Claim settled redemption proceeds. Claims the full claimable balance by
+ * default; throws NOTHING_CLAIMABLE when it is zero.
+ */
+declare function buildClaimUsdcTx(client: SuiClient, cfg: AlphaVaultConfig, params: {
+    sender: string;
+    amount?: bigint;
+}): Promise<BuildResult>;
+/** Read a user's AlphaVault position in one devInspect round-trip. */
+declare function getAlphaPosition(client: SuiClient, cfg: AlphaVaultConfig, address: string): Promise<AlphaPosition>;
+
+export { type AlphaPosition, type AlphaVaultConfig, SHARE_DECIMALS, SUI_ACTION, SUI_RECORD_STATUS, type SuiBuildResult, type SuiNetwork, type SuiUserRecord, type SuiVaultConfig, SuiVaultError, type SuiVaultErrorCode, type SuiVaultPosition, type SuiVaultState, USDC_DECIMALS, buildCancelDepositTx, buildCancelRequestTx, buildClaimTx, buildClaimUsdcTx, buildDepositTx, buildInstantRedeemTx, buildQueueRedeemTx, buildRequestRedemptionTx, buildSubscribeTx, buildTransferUsdcTx, getAlphaPosition, getAlphaVaultConfig, getSuiVaultConfig, getUserPosition, getUserRecords, getVaultState, listSuiVaults };

package/dist/index.d.ts

@@ -0,0 +1,226 @@
+import { SuiClient } from '@mysten/sui/client';
+
+/**
+ * Sui vault registry — contract object ids per network.
+ *
+ * Source of truth: tokenized-asset-claim-portal deployments (mirrored in
+ * tbook-vault-fe/lib/contracts.ts and verified against the Kotlin backend's
+ * authoritative list). Object ids are stable across package upgrades on Sui;
+ * PACKAGE_ID changes on upgrade — keep in sync with DEPLOYMENTS notes.
+ */
+type SuiNetwork = "mainnet" | "testnet";
+interface SuiVaultConfig {
+    /** Catalog vault id (matches the API catalog). */
+    id: string;
+    network: SuiNetwork;
+    packageId: string;
+    usdcType: string;
+    rcusdpType: string;
+    vaultObjectId: string;
+    pendingDepositsId: string;
+    pendingRedeemsId: string;
+    balancesId: string;
+    claimsId: string;
+    userRecordsId: string;
+    vaultTypeConfigId: string;
+    depositSettlementStateId: string;
+}
+declare const USDC_DECIMALS = 6;
+declare const SHARE_DECIMALS = 6;
+declare function getSuiVaultConfig(vaultId: string, network: SuiNetwork): SuiVaultConfig;
+declare function listSuiVaults(network: SuiNetwork): SuiVaultConfig[];
+type SuiVaultErrorCode = "UNKNOWN_VAULT" | "INSUFFICIENT_BALANCE" | "NOTHING_CLAIMABLE" | "RPC_ERROR";
+declare class SuiVaultError extends Error {
+    readonly code: SuiVaultErrorCode;
+    constructor(code: SuiVaultErrorCode, message: string);
+}
+
+/**
+ * Unsigned PTB builders for the rcUSDP Sui vault (vault_api module).
+ *
+ * Ported from tbook-vault-fe/hooks/use-vault-actions.ts, stripped of React
+ * and signing — every builder returns base64 tx bytes for the caller's
+ * wallet infrastructure (WaaS, multisig, CLI) to sign and submit.
+ *
+ * Gas: `tx.build()` selects gas coins owned by `sender`; the sender needs
+ * SUI for gas. Sponsored transactions are a later iteration.
+ */
+
+interface SuiBuildResult {
+    /** Unsigned transaction bytes, base64 — contract format `sui:tx-bytes-base64`. */
+    txBytesBase64: string;
+    /** Human-readable description of what the transaction does. */
+    message: string;
+}
+/** Deposit USDC into the vault (T+1 settlement). `amount` in raw units (1e6). */
+declare function buildDepositTx(client: SuiClient, cfg: SuiVaultConfig, params: {
+    sender: string;
+    amount: bigint;
+}): Promise<SuiBuildResult>;
+/** Queue a redemption for USDC (settles with the next cycle). `shares` raw (1e6). */
+declare function buildQueueRedeemTx(client: SuiClient, cfg: SuiVaultConfig, params: {
+    sender: string;
+    shares: bigint;
+}): Promise<SuiBuildResult>;
+/** Instant redemption to USDC (immediate, higher fee). `shares` raw (1e6). */
+declare function buildInstantRedeemTx(client: SuiClient, cfg: SuiVaultConfig, params: {
+    sender: string;
+    shares: bigint;
+}): Promise<SuiBuildResult>;
+/** Cancel a pending deposit by record id (only while its cycle is accepting). */
+declare function buildCancelDepositTx(client: SuiClient, cfg: SuiVaultConfig, params: {
+    sender: string;
+    recordId: string | bigint;
+}): Promise<SuiBuildResult>;
+/**
+ * Plain USDC transfer (treasury withdrawals to allowlisted addresses).
+ * `amount` in raw units (1e6).
+ */
+declare function buildTransferUsdcTx(client: SuiClient, cfg: SuiVaultConfig, params: {
+    sender: string;
+    recipient: string;
+    amount: bigint;
+}): Promise<SuiBuildResult>;
+/**
+ * Claim settled redemption proceeds. Claims the full claimable balance by
+ * default (contract semantics: claim pays the account's own wallet).
+ * Throws NOTHING_CLAIMABLE when the claimable balance is zero.
+ */
+declare function buildClaimTx(client: SuiClient, cfg: SuiVaultConfig, params: {
+    sender: string;
+    amount?: bigint;
+}): Promise<SuiBuildResult>;
+
+/**
+ * Read queries for the rcUSDP Sui vault.
+ *
+ * Position reads use a single devInspect batch over the vault module's view
+ * functions (ported from tbook-vault-fe/hooks/use-vault-user.ts); vault
+ * state reads the shared Vault object's fields.
+ */
+
+interface SuiVaultPosition {
+    /** Settled shares (1e6). */
+    shares: bigint;
+    /** USDC pending in the current deposit cycle (1e6). */
+    pendingDeposit: bigint;
+    /** Shares queued for redemption (1e6). */
+    pendingRedeem: bigint;
+    /** Settled USDC awaiting claim (1e6). */
+    claimable: bigint;
+}
+interface SuiVaultState {
+    paused: boolean;
+    totalShares: bigint;
+    sharePrice1e18: bigint;
+    depositFeeBps: number;
+    redeemFeeBps: number;
+    raw: Record<string, unknown>;
+}
+/** Fetch a user's full position in one devInspect round-trip. */
+declare function getUserPosition(client: SuiClient, cfg: SuiVaultConfig, address: string): Promise<SuiVaultPosition>;
+/** Read the shared Vault object's state fields. */
+declare function getVaultState(client: SuiClient, cfg: SuiVaultConfig): Promise<SuiVaultState>;
+
+/**
+ * Per-user record reads (UserRecords table) — devInspect over
+ * vault::get_all_user_records, BCS layout ported from
+ * tbook-vault-fe/hooks/use-transaction-history.ts.
+ */
+
+/** Action codes from vault.move. */
+declare const SUI_ACTION: {
+    readonly DEPOSIT: 0;
+    readonly REDEEM: 1;
+    readonly CLAIM: 2;
+    readonly INSTANT_REDEEM: 3;
+    readonly WITHDRAW_RCUSDP: 4;
+    readonly CANCEL_DEPOSIT: 5;
+};
+/** Record status codes from vault.move. */
+declare const SUI_RECORD_STATUS: {
+    readonly PENDING: 0;
+    readonly COMPLETED: 1;
+    readonly CANCELLED: 2;
+};
+interface SuiUserRecord {
+    recordId: string;
+    action: number;
+    /** Raw units (1e6). */
+    amount: bigint;
+    fee: bigint;
+    shares: bigint;
+    status: number;
+    /** Unix ms. */
+    createdAt: number;
+    /** Unix ms; 0 while pending. */
+    settledAt: number;
+    relatedRecordId: string;
+}
+/** Fetch all of a user's vault records, newest first. */
+declare function getUserRecords(client: SuiClient, cfg: SuiVaultConfig, address: string): Promise<SuiUserRecord[]>;
+
+/**
+ * AlphaVault (XAUa tokenized gold) — Sui direct rail builders and reads.
+ *
+ * Contract: rwa-alpha-token `alpha_vault` module. Subscription/redemption
+ * are request-based with T+3 issuer settlement; all user entries take the
+ * single shared AlphaVault object + Clock. Wallets must be whitelisted by
+ * the issuer before subscribing (contract `not_whitelisted` semantics).
+ *
+ * XAUA has 6 decimals (shares are u128 in the same scale); USDC is 1e6.
+ */
+
+interface AlphaVaultConfig {
+    /** Catalog vault id ("xaua-sui"). */
+    id: string;
+    network: "mainnet" | "testnet";
+    packageId: string;
+    vaultObjectId: string;
+    usdcType: string;
+    xauaType: string;
+}
+declare function getAlphaVaultConfig(vaultId: string, network: "mainnet" | "testnet"): AlphaVaultConfig;
+interface AlphaPosition {
+    /** XAUA shares free to redeem (1e6 scale, u128 on-chain). */
+    availableShares: bigint;
+    /** Shares locked in pending redemption requests. */
+    lockedShares: bigint;
+    /** Settled USDC awaiting claim (1e6). */
+    claimableUsdc: bigint;
+    totalSubscribedUsdc: bigint;
+    totalRedeemedShares: bigint;
+    totalClaimedUsdc: bigint;
+}
+interface BuildResult {
+    txBytesBase64: string;
+    message: string;
+}
+/** Subscribe USDC for XAUa at the settlement cycle's NAV (T+3). */
+declare function buildSubscribeTx(client: SuiClient, cfg: AlphaVaultConfig, params: {
+    sender: string;
+    amount: bigint;
+}): Promise<BuildResult>;
+/** Queue a redemption of XAUa shares (T+3 issuer settlement). */
+declare function buildRequestRedemptionTx(client: SuiClient, cfg: AlphaVaultConfig, params: {
+    sender: string;
+    shares: bigint;
+}): Promise<BuildResult>;
+/** Cancel a pending subscription or redemption request by id. */
+declare function buildCancelRequestTx(client: SuiClient, cfg: AlphaVaultConfig, params: {
+    sender: string;
+    requestId: string | bigint;
+    kind: "subscription" | "redemption";
+}): Promise<BuildResult>;
+/**
+ * Claim settled redemption proceeds. Claims the full claimable balance by
+ * default; throws NOTHING_CLAIMABLE when it is zero.
+ */
+declare function buildClaimUsdcTx(client: SuiClient, cfg: AlphaVaultConfig, params: {
+    sender: string;
+    amount?: bigint;
+}): Promise<BuildResult>;
+/** Read a user's AlphaVault position in one devInspect round-trip. */
+declare function getAlphaPosition(client: SuiClient, cfg: AlphaVaultConfig, address: string): Promise<AlphaPosition>;
+
+export { type AlphaPosition, type AlphaVaultConfig, SHARE_DECIMALS, SUI_ACTION, SUI_RECORD_STATUS, type SuiBuildResult, type SuiNetwork, type SuiUserRecord, type SuiVaultConfig, SuiVaultError, type SuiVaultErrorCode, type SuiVaultPosition, type SuiVaultState, USDC_DECIMALS, buildCancelDepositTx, buildCancelRequestTx, buildClaimTx, buildClaimUsdcTx, buildDepositTx, buildInstantRedeemTx, buildQueueRedeemTx, buildRequestRedemptionTx, buildSubscribeTx, buildTransferUsdcTx, getAlphaPosition, getAlphaVaultConfig, getSuiVaultConfig, getUserPosition, getUserRecords, getVaultState, listSuiVaults };