@bigmaxwatermelon/sdk 0.4.0

package/dist/index.d.ts

@@ -0,0 +1,580 @@
+import { ContractRunner, Contract, ethers } from 'ethers';
+
+interface ContractAddresses {
+    platform?: string;
+    factory?: string;
+    beacon?: string;
+}
+declare function getContracts(addresses: ContractAddresses, runner: ContractRunner): {
+    platform: Contract;
+    factory: Contract;
+    beacon: Contract;
+};
+declare function getStableCoin(address: string, runner: ContractRunner): Contract;
+
+interface PlatformInfo {
+    address: string;
+    paused: boolean;
+    tokenCount: bigint;
+    platformAdminCount: bigint;
+    approvedIssuerCount: bigint;
+    accessUserCount: bigint;
+}
+interface PlatformRoles {
+    address: string;
+    isOwner: boolean;
+    isPlatformAdmin: boolean;
+    isApprovedIssuer: boolean;
+    isAccessUser: boolean;
+}
+declare class PlatformRpcService {
+    private contracts;
+    private platform;
+    constructor(addresses: ContractAddresses, runner: ContractRunner);
+    getPlatformInfo(): Promise<PlatformInfo>;
+    getAllTokens(): Promise<string[]>;
+    getAccountRoles(account: string): Promise<PlatformRoles>;
+    isPaused(): Promise<boolean>;
+}
+
+declare class FactoryRpcService {
+    private addresses;
+    private runner;
+    constructor(addresses: ContractAddresses, runner: ContractRunner);
+    getBeaconAddress(): Promise<string>;
+    getPlatformAddress(): Promise<string>;
+}
+
+interface TokenInfo {
+    address: string;
+    name: string;
+    symbol: string;
+    decimals: number;
+    totalSupply: bigint;
+    paused: boolean;
+}
+interface TokenStats {
+    address: string;
+    holdersTotal: bigint;
+    totalMinted: bigint;
+    totalBurned: bigint;
+    totalAllowance: bigint;
+    mintersCount: bigint;
+    blacklistCount: bigint;
+}
+interface TokenRoles {
+    address: string;
+    account: string;
+    isTokenOwner: boolean;
+    isMasterMinter: boolean;
+    isMinter: boolean;
+    isBlacklistManager: boolean;
+    isMasterStatus: boolean;
+}
+declare class StableCoinRpcService {
+    private runner;
+    constructor(_addresses: ContractAddresses, runner: ContractRunner);
+    getTokenInfo(address: string): Promise<TokenInfo>;
+    getTokenStats(address: string): Promise<TokenStats>;
+    getUserRoles(address: string, account: string): Promise<TokenRoles>;
+    isPaused(address: string): Promise<boolean>;
+    isBlacklisted(address: string, user: string): Promise<boolean>;
+}
+
+type WalletMode = 'eip1193' | 'privatekey' | 'readonly';
+interface IWallet {
+    readonly mode: WalletMode;
+    /** For read operations */
+    readonly provider: ethers.Provider;
+    /** For write operations (may equal provider in read-only mode) */
+    readonly signer: ethers.Signer | null;
+    getAddress(): Promise<string | null>;
+    isConnected(): boolean;
+}
+declare class ReadOnlyWallet implements IWallet {
+    readonly mode: WalletMode;
+    readonly provider: ethers.Provider;
+    readonly signer: null;
+    constructor(rpcUrl: string);
+    getAddress(): Promise<string | null>;
+    isConnected(): boolean;
+}
+declare class PrivateKeyWallet implements IWallet {
+    readonly mode: WalletMode;
+    readonly provider: ethers.Provider;
+    readonly signer: ethers.Signer;
+    constructor(rpcUrl: string, privateKey: string);
+    getAddress(): Promise<string | null>;
+    isConnected(): boolean;
+}
+declare function createWallet(rpcUrl: string, privateKey?: string): IWallet;
+
+/**
+ * WriteExecutor — unified write transaction executor
+ *
+ * Consistent interface for all write operations:
+ * - simulate: dry-run via estimateGas only
+ * - execute: real transaction with receipt
+ * - unified error model with human-readable codes
+ * - CLI output helpers with --json / --simulate support
+ */
+
+interface SimulateResult {
+    ok: true;
+    estimatedGas: bigint;
+    functionFragment: string;
+    params: Record<string, unknown>;
+}
+interface TxReceipt {
+    txHash: string;
+    blockNumber: number | null;
+    blockHash: string | null;
+    status: number | null;
+    gasUsed: bigint;
+    effectiveGasPrice: bigint;
+    from: string;
+    to: string | null;
+    nonce: number;
+    logs: Array<{
+        address: string;
+        topics: string[];
+        data: string;
+        blockNumber: number | null;
+    }>;
+}
+interface ExecuteResult {
+    ok: true;
+    receipt: TxReceipt;
+}
+type WriteErrorCode = 'NO_SIGNER' | 'INVALID_KEY' | 'INVALID_ARGUMENT' | 'SIMULATION_FAILED' | 'REVERT' | 'ACCESS_DENIED' | 'INSUFFICIENT_BALANCE' | 'INSUFFICIENT_ALLOWANCE' | 'PAUSED' | 'BLACKLISTED' | 'NOT_APPROVED_ISSUER' | 'FACTORY_SYMBOL_EXISTS' | 'ZERO_ADDRESS' | 'RPC_ERROR' | 'UNKNOWN';
+interface WriteError {
+    ok: false;
+    code: WriteErrorCode;
+    message: string;
+    details?: unknown;
+}
+type WriteResult = SimulateResult | ExecuteResult | WriteError;
+interface WriteCall {
+    method: string;
+    args: unknown[];
+    overrides?: Record<string, unknown>;
+}
+interface WriteExecutorConfig {
+    wallet: IWallet;
+    contract: Contract;
+}
+declare class WriteExecutor {
+    private config;
+    constructor(config: WriteExecutorConfig);
+    /** Dry-run: estimate gas without signing. Returns gas estimate or decoded error. */
+    simulate(call: WriteCall): Promise<SimulateResult | WriteError>;
+    /** Execute: sign and broadcast, wait for receipt. */
+    execute(call: WriteCall, confirmations?: number): Promise<ExecuteResult | WriteError>;
+    private parseRevertError;
+}
+interface WriteOpts {
+    simulate: boolean;
+    json: boolean;
+}
+interface WriteMeta {
+    chainId: number;
+    source: 'rpc';
+    timestamp: number;
+    command?: string;
+}
+declare function makeWriteMeta(command?: string): WriteMeta;
+
+declare class GraphError extends Error {
+    readonly code: 'NETWORK_ERROR' | 'SUBGRAPH_ERROR' | 'PARSE_ERROR' | 'UNKNOWN';
+    readonly details?: unknown | undefined;
+    constructor(message: string, code: 'NETWORK_ERROR' | 'SUBGRAPH_ERROR' | 'PARSE_ERROR' | 'UNKNOWN', details?: unknown | undefined);
+}
+interface GraphClientConfig {
+    endpoint: string;
+    /** Optional headers (e.g. authorization) */
+    headers?: Record<string, string>;
+}
+declare class GraphClient {
+    private client;
+    constructor(config: GraphClientConfig);
+    /**
+     * Execute a raw GraphQL query.
+     * @param query - GraphQL query string
+     * @param variables - Optional query variables
+     */
+    query<T>(query: string, variables?: Record<string, unknown>): Promise<T>;
+    /**
+     * Ping the subgraph — useful for health checks.
+     * Returns current block number or throws.
+     */
+    ping(): Promise<{
+        number: number;
+        hash: string;
+        deployment: string;
+    }>;
+    private normalizeError;
+}
+
+/** Bytes in subgraph = hex string with 0x prefix */
+type Bytes = string;
+/** BigInt in subgraph = decimal string */
+type BigInt = string;
+type TokenStatus = 'ACTIVE' | 'PAUSED';
+interface Token {
+    id: Bytes;
+    address: Bytes;
+    name: string;
+    symbol: string;
+    decimals: number;
+    creator: Bytes;
+    createdAt: BigInt;
+    status: TokenStatus;
+    activeHolderCount: BigInt;
+    totalMintCount: BigInt;
+    totalMintAmount: BigInt;
+    totalBurnCount: BigInt;
+    totalBurnAmount: BigInt;
+    lastUpdatedAt: BigInt;
+}
+interface TokenHolder {
+    id: string;
+    token: Bytes;
+    address: Bytes;
+    balance: BigInt;
+    firstSeenAt: BigInt;
+    hasMinted: boolean;
+    hasBurned: boolean;
+}
+interface Token24hSnapshot {
+    id: string;
+    token: Bytes;
+    mintAmount24h: BigInt;
+    burnAmount24h: BigInt;
+    mintCount24h: BigInt;
+    burnCount24h: BigInt;
+    lastUpdatedAt: BigInt;
+}
+interface TokenRegisteredEvent {
+    id: string;
+    operator: Bytes;
+    token: Bytes;
+    name: string;
+    symbol: string;
+    memo: string;
+    blockNumber: BigInt;
+    timestamp: BigInt;
+    transactionHash: Bytes;
+}
+interface MintEvent {
+    id: string;
+    token: Bytes;
+    operator: Bytes;
+    to: Bytes;
+    amount: BigInt;
+    memo: string;
+    blockNumber: BigInt;
+    timestamp: BigInt;
+    transactionHash: Bytes;
+}
+interface BurnEvent {
+    id: string;
+    token: Bytes;
+    operator: Bytes;
+    from: Bytes;
+    amount: BigInt;
+    memo: string;
+    blockNumber: BigInt;
+    timestamp: BigInt;
+    transactionHash: Bytes;
+}
+interface TransferEvent {
+    id: string;
+    token: Bytes;
+    from: Bytes;
+    to: Bytes;
+    amount: BigInt;
+    blockNumber: BigInt;
+    timestamp: BigInt;
+    transactionHash: Bytes;
+}
+interface PauseEvent {
+    id: string;
+    token: Bytes;
+    account: Bytes;
+    action: string;
+    blockNumber: BigInt;
+    timestamp: BigInt;
+    transactionHash: Bytes;
+}
+interface PausedByOwnerEvent {
+    id: string;
+    token: Bytes;
+    account: Bytes;
+    memo: string;
+    blockNumber: BigInt;
+    timestamp: BigInt;
+    transactionHash: Bytes;
+}
+interface UnpausedByOwnerEvent {
+    id: string;
+    token: Bytes;
+    account: Bytes;
+    memo: string;
+    blockNumber: BigInt;
+    timestamp: BigInt;
+    transactionHash: Bytes;
+}
+interface BlacklistEvent {
+    id: string;
+    token: Bytes;
+    operator: Bytes;
+    user: Bytes;
+    action: string;
+    memo: string;
+    blockNumber: BigInt;
+    timestamp: BigInt;
+    transactionHash: Bytes;
+}
+interface PlatformAdmin {
+    id: string;
+    account: Bytes;
+    isActive: boolean;
+    lastOperator: Bytes;
+    addedAt: BigInt;
+    removedAt: BigInt | null;
+    addedCount: BigInt;
+    removedCount: BigInt;
+    lastUpdatedAt: BigInt;
+}
+interface ApprovedIssuer {
+    id: string;
+    account: Bytes;
+    isActive: boolean;
+    lastOperator: Bytes;
+    addedAt: BigInt;
+    removedAt: BigInt | null;
+    addedCount: BigInt;
+    removedCount: BigInt;
+    lastUpdatedAt: BigInt;
+}
+interface AccessUser {
+    id: string;
+    account: Bytes;
+    isActive: boolean;
+    lastOperator: Bytes;
+    addedAt: BigInt;
+    removedAt: BigInt | null;
+    addedCount: BigInt;
+    removedCount: BigInt;
+    lastUpdatedAt: BigInt;
+}
+interface FactoryInitializedEvent {
+    id: string;
+    version: BigInt;
+    blockNumber: BigInt;
+    timestamp: BigInt;
+    transactionHash: Bytes;
+}
+interface FactorySetEvent {
+    id: string;
+    operator: Bytes;
+    oldFactory: Bytes;
+    newFactory: Bytes;
+    blockNumber: BigInt;
+    timestamp: BigInt;
+    transactionHash: Bytes;
+}
+interface MinterAddedEvent {
+    id: string;
+    token: Bytes;
+    operator: Bytes;
+    minter: Bytes;
+    memo: string;
+    blockNumber: BigInt;
+    timestamp: BigInt;
+    transactionHash: Bytes;
+}
+interface MinterRemovedEvent {
+    id: string;
+    token: Bytes;
+    operator: Bytes;
+    minter: Bytes;
+    memo: string;
+    blockNumber: BigInt;
+    timestamp: BigInt;
+    transactionHash: Bytes;
+}
+
+declare class TokenHistoryService {
+    private client;
+    constructor(client: GraphClient);
+    getToken(address: string): Promise<Token | null>;
+    getTokens(first?: number, skip?: number): Promise<Token[]>;
+    getTokenCreatedEvents(first?: number, skip?: number): Promise<TokenRegisteredEvent[]>;
+    getMintHistory(tokenAddress: string, first?: number, skip?: number): Promise<MintEvent[]>;
+    getBurnHistory(tokenAddress: string, first?: number, skip?: number): Promise<BurnEvent[]>;
+    getTransferHistory(tokenAddress: string, first?: number, skip?: number): Promise<TransferEvent[]>;
+    getPauseHistory(tokenAddress: string, first?: number, skip?: number): Promise<PauseEvent[]>;
+    getPausedByOwnerHistory(tokenAddress: string, first?: number, skip?: number): Promise<PausedByOwnerEvent[]>;
+    getUnpausedByOwnerHistory(tokenAddress: string, first?: number, skip?: number): Promise<UnpausedByOwnerEvent[]>;
+    getBlacklistHistory(tokenAddress: string, first?: number, skip?: number): Promise<BlacklistEvent[]>;
+    getHolders(tokenAddress: string, first?: number, skip?: number): Promise<TokenHolder[]>;
+    get24hSnapshot(tokenAddress: string): Promise<Token24hSnapshot | null>;
+    getMinterAddedHistory(tokenAddress: string, first?: number, skip?: number): Promise<MinterAddedEvent[]>;
+    getMinterRemovedHistory(tokenAddress: string, first?: number, skip?: number): Promise<MinterRemovedEvent[]>;
+}
+
+declare class PlatformHistoryService {
+    private client;
+    constructor(client: GraphClient);
+    getPlatformAdmins(first?: number, skip?: number): Promise<PlatformAdmin[]>;
+    getActivePlatformAdins(): Promise<PlatformAdmin[]>;
+    getApprovedIssuers(first?: number, skip?: number): Promise<ApprovedIssuer[]>;
+    getActiveApprovedIssuers(): Promise<ApprovedIssuer[]>;
+    getAccessUsers(first?: number, skip?: number): Promise<AccessUser[]>;
+    getActiveAccessUsers(): Promise<AccessUser[]>;
+    getFactoryInitializedEvents(first?: number, skip?: number): Promise<FactoryInitializedEvent[]>;
+    getFactorySetEvents(first?: number, skip?: number): Promise<FactorySetEvent[]>;
+}
+
+declare class AnalyticsService {
+    readonly token: TokenHistoryService;
+    readonly platform: PlatformHistoryService;
+    constructor(graph: GraphClient);
+    /**
+     * Get a quick supply summary for a token.
+     * Combines live token stats (from GQL) with 24h snapshot.
+     */
+    getTokenSupplySummary(tokenAddress: string): Promise<{
+        tokenAddress: string;
+        name: string;
+        symbol: string;
+        status: TokenStatus;
+        totalMintAmount: bigint;
+        totalBurnAmount: bigint;
+        netSupply: bigint;
+        activeHolderCount: number;
+        snapshot: {
+            mintAmount24h: bigint;
+            burnAmount24h: bigint;
+            mintCount24h: number;
+            burnCount24h: number;
+        } | null;
+    } | null>;
+    /**
+     * Get top N holders for a token.
+     * Returns address + balance sorted by balance descending.
+     */
+    getTopHolders(tokenAddress: string, limit?: number): Promise<{
+        address: string;
+        balance: bigint;
+    }[]>;
+    /**
+     * Get recent activity (mint + burn events) for a token.
+     * Useful for a quick activity feed.
+     */
+    getRecentActivity(tokenAddress: string, limit?: number): Promise<{
+        type: "mint" | "burn";
+        txHash: string;
+        blockNumber: bigint;
+        timestamp: bigint;
+        amount: bigint;
+        actor: string;
+    }[]>;
+    /**
+     * Get a holder balance across all their holdings.
+     * Useful for an address summary view.
+     */
+    getAccountPortfolio(ethAddress: string): Promise<Array<{
+        token: string;
+        balance: bigint;
+    }>>;
+}
+
+interface IsometryGraphConfig {
+    endpoint: string;
+    headers?: Record<string, string>;
+}
+/**
+ * Create all graph services from a single config.
+ * Convenience wrapper — individual services are also importable directly.
+ */
+declare function createGraphClient(config: IsometryGraphConfig): {
+    client: GraphClient;
+    token: TokenHistoryService;
+    platform: PlatformHistoryService;
+    analytics: AnalyticsService;
+};
+
+/**
+ * IsometryClient — RPC + Graph 双通道聚合
+ */
+
+interface IsometryConfig {
+    chainId?: number;
+    rpcUrl?: string;
+    graphUrl?: string;
+    addresses?: ContractAddresses;
+    privateKey?: string;
+}
+declare const SDK_VERSION = "0.4.0";
+declare class IsometryClient {
+    readonly rpc: {
+        platform: PlatformRpcService;
+        factory: FactoryRpcService;
+        token: StableCoinRpcService;
+    };
+    readonly graph: ReturnType<typeof createGraphClient>;
+    readonly config: {
+        chainId: number;
+        rpcUrl: string;
+        graphUrl: string;
+        addresses: ContractAddresses;
+        privateKey: string | undefined;
+        walletMode: string;
+    };
+    private _wallet;
+    private _addresses;
+    private _chainId;
+    constructor(config?: IsometryConfig);
+    /** Validate chain ID matches configured value */
+    validateChain(): Promise<void>;
+    /** Get connected address (null if read-only) */
+    getAddress(): Promise<string | null>;
+    destroy(): Promise<void>;
+}
+declare function createClient(config?: IsometryConfig): IsometryClient;
+
+/**
+ * Error selector → human-readable code mapping
+ *
+ * Observed on Sepolia (from live testing):
+ * - 0xe2517d3f = OpenZeppelin AccessControlUnauthorizedAccount
+ * - 0x08c379a0 = Error(string) — "Not authorized", "Not approved issuer"
+ *
+ * Extend this map as new selectors are observed on-chain.
+ */
+interface DecodedError {
+    code: string;
+    message: string;
+}
+/**
+ * Maps 4-byte error selector (0x...) to { code, message }.
+ * Code is a SCREAMING_SNAKE_CASE identifier suitable for JSON output.
+ */
+declare const ERROR_SELECTOR_MAP: Record<string, DecodedError>;
+/**
+ * Decode an ethers CALL_EXCEPTION error details object.
+ * Returns a DecodedError if the selector is known, otherwise null.
+ */
+declare function decodeError(details: {
+    data?: string;
+    revert?: {
+        signature?: string;
+        name?: string;
+        args?: unknown[];
+    };
+    reason?: string | null;
+}): DecodedError | null;
+
+export { AnalyticsService, type ContractAddresses, type DecodedError, ERROR_SELECTOR_MAP, type ExecuteResult, GraphClient, GraphError, type IWallet, IsometryClient, type IsometryConfig, type IsometryGraphConfig, PlatformHistoryService, type PlatformInfo, type PlatformRoles, PrivateKeyWallet, ReadOnlyWallet, SDK_VERSION, type SimulateResult, TokenHistoryService, type TokenInfo, type TokenRoles, type TokenStats, type TxReceipt, type WalletMode, type WriteError, type WriteErrorCode, WriteExecutor, type WriteMeta, type WriteOpts, type WriteResult, createClient, createGraphClient, createWallet, decodeError, getContracts, getStableCoin, makeWriteMeta };