import { PublicClient, Address, WalletClient, Chain, Account, WalletActions, SimulateContractParameters, TransactionReceipt } from 'viem'; declare const FV_IDENTIFIER_MSG2 = "Sign this message to request verifying your account and to create your own secret unique identifier for your anonymized record.\nYou can use this identifier in the future to delete this anonymized record.\nWARNING: do not sign this message unless you trust the website/application requesting this signature."; type contractEnv = "production" | "staging" | "development"; declare const Envs: Record>; interface ContractAddresses { identityContract: `0x${string}`; ubiContract: `0x${string}`; faucetContract: `0x${string}`; g$Contract: `0x${string}`; } declare enum SupportedChains$1 { "FUSE" = 122, "CELO" = 42220, "XDC" = 50 } type SupportedChainId = `${SupportedChains$1}` extends infer _ ? SupportedChains$1 : SupportedChains$1; interface ChainConfig { id: SupportedChains$1; key: keyof typeof SupportedChains$1; label: string; shortName: string; explorer: { address: (address: string) => string; tx: (hash: string) => string; }; rpcUrls: string[]; defaultGasPrice?: bigint; claimGasBuffer: bigint; fvDefaultChain?: SupportedChains$1; contracts: Partial>; } declare const FALLBACK_CHAIN_PRIORITY: readonly SupportedChains$1[]; declare const CHAIN_DECIMALS: Record; declare const chainConfigs: Record; declare const SUPPORTED_CHAIN_IDS: SupportedChains$1[]; declare const isSupportedChain: (chainId: number | undefined) => chainId is SupportedChains$1; declare const createRpcUrlIterator: (chainId: SupportedChains$1) => () => string; /** * Core identity ABI — includes both read/write identity methods * and IdentityV4 wallet-link methods (connectAccount, disconnectAccount, connectedAccounts). */ declare const identityV2ABI: readonly [{ readonly name: "addWhitelisted"; readonly type: "function"; readonly stateMutability: "nonpayable"; readonly inputs: readonly [{ readonly type: "address"; readonly name: "account"; }]; readonly outputs: readonly []; }, { readonly name: "removeWhitelisted"; readonly type: "function"; readonly stateMutability: "nonpayable"; readonly inputs: readonly [{ readonly type: "address"; readonly name: "account"; }]; readonly outputs: readonly []; }, { readonly name: "getWhitelistedRoot"; readonly type: "function"; readonly stateMutability: "view"; readonly inputs: readonly [{ readonly type: "address"; readonly name: "account"; }]; readonly outputs: readonly [{ readonly type: "address"; }]; }, { readonly name: "lastAuthenticated"; readonly type: "function"; readonly stateMutability: "view"; readonly inputs: readonly [{ readonly type: "address"; readonly name: "account"; }]; readonly outputs: readonly [{ readonly type: "uint256"; }]; }, { readonly name: "authenticationPeriod"; readonly type: "function"; readonly stateMutability: "view"; readonly inputs: readonly []; readonly outputs: readonly [{ readonly type: "uint256"; }]; }, { readonly name: "connectAccount"; readonly type: "function"; readonly stateMutability: "nonpayable"; readonly inputs: readonly [{ readonly type: "address"; readonly name: "account"; }]; readonly outputs: readonly []; }, { readonly name: "disconnectAccount"; readonly type: "function"; readonly stateMutability: "nonpayable"; readonly inputs: readonly [{ readonly type: "address"; readonly name: "account"; }]; readonly outputs: readonly []; }, { readonly name: "connectedAccounts"; readonly type: "function"; readonly stateMutability: "view"; readonly inputs: readonly [{ readonly type: "address"; readonly name: "account"; }]; readonly outputs: readonly [{ readonly type: "address"; }]; }]; declare const ubiSchemeV2ABI: readonly [{ readonly name: "claim"; readonly type: "function"; readonly stateMutability: "nonpayable"; readonly inputs: readonly []; readonly outputs: readonly [{ readonly type: "bool"; }]; }, { readonly name: "checkEntitlement"; readonly type: "function"; readonly stateMutability: "view"; readonly inputs: readonly []; readonly outputs: readonly [{ readonly type: "uint256"; }]; }, { readonly name: "checkEntitlement"; readonly type: "function"; readonly stateMutability: "view"; readonly inputs: readonly [{ readonly type: "address"; readonly name: "_member"; }]; readonly outputs: readonly [{ readonly type: "uint256"; }]; }, { readonly name: "getDailyStats"; readonly type: "function"; readonly stateMutability: "view"; readonly inputs: readonly []; readonly outputs: readonly [{ readonly type: "uint256"; readonly name: "claimers"; }, { readonly type: "uint256"; readonly name: "amount"; }]; }, { readonly name: "periodStart"; readonly type: "function"; readonly stateMutability: "view"; readonly inputs: readonly []; readonly outputs: readonly [{ readonly type: "uint256"; }]; }, { readonly name: "currentDay"; readonly type: "function"; readonly stateMutability: "view"; readonly inputs: readonly []; readonly outputs: readonly [{ readonly type: "uint256"; }]; }, { readonly name: "UBIClaimed"; readonly type: "event"; readonly inputs: readonly [{ readonly type: "address"; readonly name: "account"; readonly indexed: true; }, { readonly type: "uint256"; readonly name: "amount"; }]; }]; declare const faucetABI: readonly [{ readonly name: "minTopping"; readonly type: "function"; readonly stateMutability: "view"; readonly inputs: readonly []; readonly outputs: readonly [{ readonly type: "uint8"; }]; }, { readonly name: "getToppingAmount"; readonly type: "function"; readonly stateMutability: "view"; readonly inputs: readonly []; readonly outputs: readonly [{ readonly type: "uint256"; }]; }, { readonly name: "canTop"; readonly type: "function"; readonly stateMutability: "view"; readonly inputs: readonly [{ readonly type: "address"; readonly name: "_user"; }]; readonly outputs: readonly [{ readonly type: "bool"; }]; }, { readonly name: "topWallet"; readonly type: "function"; readonly stateMutability: "payable"; readonly inputs: readonly [{ readonly type: "address"; readonly name: "_user"; }]; readonly outputs: readonly []; }]; declare const g$ABI: readonly [{ readonly name: "balanceOf"; readonly type: "function"; readonly stateMutability: "view"; readonly inputs: readonly [{ readonly type: "address"; readonly name: "account"; }]; readonly outputs: readonly [{ readonly type: "uint256"; }]; }]; /** * Security messages shown to end-users before wallet-link actions. * Wallet integrators can opt out by passing `skipSecurityMessage: true` in WalletLinkOptions. */ declare const WALLET_LINK_SECURITY_MESSAGES: { readonly connect: string; readonly disconnect: string; }; interface IdentityExpiry { expiryTimestamp: bigint; formattedExpiryTimestamp?: string; } interface IdentityExpiryData { lastAuthenticated: bigint; authPeriod: bigint; } interface IdentityContract { publicClient: PublicClient; contractAddress: Address; } type SupportedChains = 42220 | 122 | 50; interface WalletLinkOptions { skipSecurityMessage?: boolean; onSecurityMessage?: (message: string) => Promise; onHash?: (hash: `0x${string}`) => void; } type WalletLinkAction = "connectAccount" | "disconnectAccount"; interface ChainConnectedStatus { chainId: number; chainName: string; isConnected: boolean; root: Address; error?: string; } /** * Initializes the Identity Contract. * @param publicClient - The PublicClient instance. * @param contractAddress - The contract address. * @returns An IdentityContract instance. */ declare const initializeIdentityContract: (publicClient: PublicClient, contractAddress: Address) => IdentityContract; interface IdentitySDKOptions { account?: Address; publicClient: PublicClient; walletClient: WalletClient; env: contractEnv; } /** * Handles interactions with the Identity Contract. */ declare class IdentitySDK { account: Address; publicClient: PublicClient; walletClient: WalletClient & WalletActions; contract: IdentityContract; env: contractEnv; private readonly chainId; private readonly fvDefaultChain; private readonly rpcIterators; /** * Initializes the IdentitySDK. * @param publicClient - The PublicClient instance. * @param walletClient - The WalletClient with WalletActions. * @param env - The environment to use ("production" | "staging" | "development"). */ constructor({ account, publicClient, walletClient, env, }: IdentitySDKOptions); static init(props: Omit): Promise; /** * Evaluates security constraints and prompts the user with security messages if required. * Custodial/automated flows can bypass this entirely via `skipSecurityMessage: true`. * For native wallet flows, `onSecurityMessage` receives the notice and must resolve * to `true` for the transaction to proceed. Without either option the message is * logged to `console.info` as a headless default. * @param action - The wallet link action being performed ("connect" or "disconnect"). * @param options - Additional wallet link options including security prompt handlers. */ private runSecurityCheck; /** * Submits a transaction and waits for its receipt. * @param params - Parameters for simulating the contract call. * @param onHash - Optional callback to receive the transaction hash. * @returns The transaction receipt. * @throws If submission fails or no active wallet address is found. */ submitAndWait(params: SimulateContractParameters, onHash?: (hash: `0x${string}`) => void): Promise; /** * Returns whitelist status of main account or any connected account. * @param account - The account address to check. * @returns An object containing whitelist status and root address. * @reference: https://docs.gooddollar.org/user-guides/connect-another-wallet-address-to-identity */ getWhitelistedRoot(account: Address): Promise<{ isWhitelisted: boolean; root: Address; }>; /** * Checks the wallet-link connection status of the given account. * * When `chainId` is provided the query is scoped to that single chain only. * When omitted, all supported chains are queried in parallel via Promise.allSettled * and one ChainConnectedStatus entry is returned per chain. * * App-provided public clients always take precedence. For the SDK's current * chain `this.publicClient` is reused when no override is passed. For other * chains the SDK falls back to local read-only RPC clients using the same * fallback flow as other multi-chain reads. * * @param account - The account address to check. * @param chainId - Optional. Restricts the query to this chain only. * @param publicClients - Optional. App-level public clients keyed by SupportedChains ID. * @returns An array of ChainConnectedStatus (one entry per queried chain). */ checkConnectedStatus(account: Address, chainId?: SupportedChains$1, publicClients?: Record): Promise; /** * Retrieves identity expiry data for a given account. * @param account - The account address. * @returns The identity expiry data. */ getIdentityExpiryData(account: Address): Promise; /** * Updates the wallet-link status of an account. * The whitelisted root identity must be the signer for `connectAccount`, * while `disconnectAccount` can be called by either the root identity or * the connected account itself. * Custodial flows can pass `skipSecurityMessage: true` to bypass the notice; * the underlying transaction signing is handled by the app-provided walletClient * (or IdentityCustodialSDK for LocalAccount signers). * @param action - The wallet-link action to submit. * @param account - The account address to update. * @param options - Additional options, such as security prompts. * @returns The transaction receipt. */ updateConnectionStatus(action: WalletLinkAction, account: Address, options?: WalletLinkOptions): Promise; /** * Connects a new account to the identity. * The whitelisted root identity must be the signer. No additional message * signature is required beyond the transaction itself. * @param account - The account address to connect. * @param options - Additional options, such as security prompts. * @returns The transaction receipt. */ connectAccount(account: Address, options?: WalletLinkOptions): Promise; /** * Disconnects an account from the identity. * Either the root identity or the connected account itself can call this. * @param account - The account address to disconnect. * @param options - Additional options, such as security prompts. * @returns The transaction receipt. */ disconnectAccount(account: Address, options?: WalletLinkOptions): Promise; /** * Generates a Face Verification Link. * @param popupMode - Whether to generate a popup link. * @param callbackUrl - The URL to callback after verification. * @param chainId - The blockchain network ID. * @returns The generated Face Verification link. */ generateFVLink(popupMode?: boolean, callbackUrl?: string, chainId?: SupportedChains$1): Promise; /** * Calculates the identity expiry timestamp. * @param lastAuthenticated - The timestamp of last authentication. * @param authPeriod - The authentication period. * @returns The identity expiry data. */ calculateIdentityExpiry(lastAuthenticated: bigint, authPeriod: bigint): IdentityExpiry; } type TransactionSubmittedCallback = (hash: `0x${string}`) => void | Promise; interface ClaimSDKOptions { account: Address; publicClient: PublicClient; walletClient: WalletClient; identitySDK: IdentitySDK; rdu?: string; env?: contractEnv; } interface WalletClaimStatus { status: "not_whitelisted" | "can_claim" | "already_claimed"; entitlement: bigint; nextClaimTime?: Date; } interface CheckEntitlementOptions { publicClient?: PublicClient; chainOverride?: SupportedChains$1; } interface CheckGenericEntitlementOptions { publicClient: PublicClient; chainId: SupportedChains$1; env?: contractEnv; } interface CheckGenericDailyStatsOptions { publicClient: PublicClient; chainId: SupportedChains$1; env?: contractEnv; } interface ClaimEntitlementResult { amount: bigint; altClaimAvailable: boolean; altChainId: SupportedChains$1 | null; altAmount: bigint | null; } type ClaimTxConfirmCallback = (message: string) => void | Promise; type ClaimTransactionSubmittedCallback = TransactionSubmittedCallback; /** * Reads the chain-level entitlement using the no-argument UBIScheme method. * This path does not require a wallet account and is suitable for * disconnected pre-connect UI states. */ declare function checkGenericEntitlement(options: CheckGenericEntitlementOptions): Promise; /** * Reads chain-level daily claim stats without requiring wallet/account context. */ declare function checkGenericDailyStats(options: CheckGenericDailyStatsOptions): Promise<{ claimers: bigint; amount: bigint; }>; declare class ClaimSDK { readonly publicClient: PublicClient; readonly walletClient: WalletClient; private readonly identitySDK; private readonly chainId; private readonly chainContracts; private readonly fallbackChains; private readonly rpcIterators; private readonly fvDefaultChain; private readonly ubiSchemeAddress; private readonly faucetAddress; private readonly account; private readonly env; readonly rdu: string; constructor({ account, publicClient, walletClient, identitySDK, rdu, env, }: ClaimSDKOptions); private getContractsForChain; private getActiveChainId; private readChainEntitlement; private findAltEntitlement; static init(props: Omit): Promise; /** * Reads a contract function using publicClient. * @param params - Parameters for the contract read operation. * @returns The result of the contract read. * @throws If the contract read fails. */ private readContract; /** * Submits a transaction and waits for its receipt. * @param params - Parameters for simulating the contract call. * @param onHash - Optional callback invoked after broadcast and before receipt confirmation. * @returns The transaction receipt. * @throws If submission fails or no active wallet address is found. */ submitAndWait(params: SimulateContractParameters, onHash?: ClaimTransactionSubmittedCallback): Promise; /** * Checks if the connected user is eligible to claim UBI for the current period. * Returns the amount they can claim (0 if not eligible or already claimed). * Does not check for whitelisting status. * @param pClient - Optional public client scoped to an alternative chain. * @param chainOverride - Optional chain id to evaluate entitlement against. * @returns The claimable amount in the smallest unit (e.g., wei). * @throws If the entitlement check fails. */ checkEntitlement(options?: CheckEntitlementOptions): Promise; /** * Checks the wallet claim status for the connected user. * This method provides a single point to check if the user can claim, needs verification, or has already claimed. * @returns WalletClaimStatus object with status, entitlement, and optionally nextClaimTime * @throws If unable to check wallet status or fetch required data. */ getWalletClaimStatus(): Promise; /** * Attempts to claim UBI for the connected user. * 1. Checks if the user is whitelisted using IdentitySDK. * 2. If not whitelisted, redirects to face verification and throws an error. * 3. If whitelisted, checks if the user can claim UBI from the pool using checkEntitlement. * 4. If whitelisted and can claim, checks if the user has sufficient balance. * 5. If the user cannot claim due to low balance, triggers a faucet request and waits. * 6. If whitelisted and can claim, proceeds to call the claim function on the UBIScheme contract. * @param onConfirmFaucetTx - Optional callback to confirm faucet or retry actions during balance checks. * @param onClaimSubmitted - Optional callback invoked after broadcast and before receipt confirmation. * @returns The transaction receipt if the claim is successful. * @throws If the user is not whitelisted, not entitled to claim, balance check fails, or claim transaction fails. */ claim(onConfirmFaucetTx?: ClaimTxConfirmCallback, onClaimSubmitted?: ClaimTransactionSubmittedCallback): Promise; /** * Redirects the user through the face-verification flow. * @throws If face verification redirect fails. */ private fvRedirect; /** * Retrieves the next available claim time for the connected user. * Returns epoch time (0) if the user can claim now (entitlement > 0). * @returns The timestamp when the user can next claim UBI, or epoch time if can claim now. * @throws If unable to fetch the next claim time. */ nextClaimTime(): Promise; /** * Gets the number of claimers and total amount claimed for the current day. * @returns An object containing the number of claimers and total amount claimed. * @throws If unable to fetch daily stats. */ getDailyStats(): Promise<{ claimers: bigint; amount: bigint; }>; /** * Triggers a faucet request to top up the user's balance. * @param txConfirm - Optional callback to confirm transactions before execution. * @throws If the faucet request fails. * * NOTE: Upgraded to contract-first flow: * - Try on-chain faucet call (user signs) via `faucet.topWallet(address)` * - Guard against gas>topping griefing and low native balance for publishing the tx * - If on-chain path fails (or cannot sign/publish), fallback to backend `/verify/topWallet` * - Throttled to at most once per hour per chain (localStorage) */ triggerFaucet(txConfirm?: (message: string) => void | Promise): Promise; /** * Fetches faucet parameters (minTopping and toppingAmount). * @returns Faucet configuration parameters. * @throws If unable to fetch faucet parameters. */ getFaucetParameters(): Promise<{ minTopping: number; toppingAmount: bigint; }>; /** * Checks the user's balance with retries, triggering a faucet request if needed. * @param txConfirm - Optional callback to confirm transactions before execution. * @returns True if the balance meets the threshold, false otherwise. * @throws If the maximum retries are exceeded or faucet request fails. */ checkBalanceWithRetry(txConfirm?: (message: string) => void | Promise): Promise; } interface ClaimCustodialSDKOptions extends Omit { } declare class ClaimCustodialSDK extends ClaimSDK { constructor(options: ClaimCustodialSDKOptions); /** * Override submitAndWait to handle LocalAccount signing for Celo RPC compatibility * Submits a transaction and waits for its receipt. * @param params - Parameters for simulating the contract call. * @param onHash - Optional callback invoked after broadcast and before receipt confirmation. * @returns The transaction receipt. * @throws If submission fails or no active wallet address is found. */ submitAndWait(params: SimulateContractParameters, onHash?: ClaimTransactionSubmittedCallback): Promise; } /** * Custodial version of IdentitySDK that handles LocalAccount signing for Celo RPC compatibility */ declare class IdentityCustodialSDK extends IdentitySDK { /** * Override submitAndWait to handle account retrieval differently for custodial wallets * @param params - Parameters for simulating the contract call. * @param onHash - Optional callback to receive the transaction hash. * @returns The transaction receipt. * @throws If submission fails or no active wallet address is found. */ submitAndWait(params: SimulateContractParameters, onHash?: (hash: `0x${string}`) => void): Promise; /** * Override generateFVLink to handle LocalAccount message signing for Celo RPC compatibility * @param popupMode - Whether to generate a popup link. * @param callbackUrl - The URL to callback after verification. * @param chainId - The blockchain network ID. * @returns The generated Face Verification link. */ generateFVLink(popupMode?: boolean, callbackUrl?: string, chainId?: number): Promise; } type SdkRuntimeNeed = "connectedWallet" | "readClient" | "walletClient" | "chainSwitching"; type SdkEffect = "signature" | "externalFlow" | "transaction"; interface SdkCapabilityOperation { id: string; method: string; needs: readonly SdkRuntimeNeed[]; effects?: readonly SdkEffect[]; } interface SdkCapabilitySummary { sdk: string; environments: readonly string[]; chains: readonly SupportedChains$1[]; needs: readonly SdkRuntimeNeed[]; reads: readonly SdkCapabilityOperation[]; writes: readonly SdkCapabilityOperation[]; } /** * Canonical citizen-sdk runtime environments for capability consumers. * Adapters/widgets should consume this via citizenSdkCapabilities to avoid * duplicating environment lists. */ declare const CITIZEN_SDK_ENVIRONMENTS: readonly ["production", "staging", "development"]; /** * Canonical citizen-sdk supported chains for capability consumers. * Adapters/widgets should consume this via citizenSdkCapabilities to avoid * duplicating supported-chain lists. */ declare const CITIZEN_SDK_SUPPORTED_CHAINS: readonly [SupportedChains$1.FUSE, SupportedChains$1.CELO, SupportedChains$1.XDC]; declare const citizenSdkCapabilities: { readonly sdk: "@goodsdks/citizen-sdk"; readonly environments: readonly ["production", "staging", "development"]; readonly chains: readonly [SupportedChains$1.FUSE, SupportedChains$1.CELO, SupportedChains$1.XDC]; readonly needs: readonly ["connectedWallet", "readClient", "walletClient", "chainSwitching"]; readonly reads: readonly [{ readonly id: "whitelistStatus"; readonly method: "IdentitySDK.getWhitelistedRoot"; readonly needs: readonly ["readClient"]; }, { readonly id: "identityExpiry"; readonly method: "IdentitySDK.getIdentityExpiryData"; readonly needs: readonly ["readClient"]; }, { readonly id: "claimStatus"; readonly method: "ClaimSDK.getWalletClaimStatus"; readonly needs: readonly ["readClient", "walletClient", "connectedWallet"]; }, { readonly id: "claimEntitlement"; readonly method: "ClaimSDK.checkEntitlement"; readonly needs: readonly ["readClient", "walletClient", "connectedWallet"]; }, { readonly id: "genericClaimEntitlement"; readonly method: "checkGenericEntitlement"; readonly needs: readonly ["readClient"]; }, { readonly id: "dailyStats"; readonly method: "checkGenericDailyStats"; readonly needs: readonly ["readClient"]; }]; readonly writes: readonly [{ readonly id: "startVerification"; readonly method: "IdentitySDK.generateFVLink"; readonly needs: readonly ["walletClient", "connectedWallet"]; readonly effects: readonly ["signature", "externalFlow"]; }, { readonly id: "claim"; readonly method: "ClaimSDK.claim"; readonly needs: readonly ["walletClient", "connectedWallet"]; readonly effects: readonly ["transaction", "signature", "externalFlow"]; }]; }; type TriggerFaucetResult = "skipped" | "topped_via_contract" | "topped_via_api" | "error"; interface TriggerFaucetParams { chainId: SupportedChains; account: Address; publicClient: PublicClient; walletClient: WalletClient; faucetAddress: Address; env: string; throttleMs?: number; } /** * Contract-first faucet top-up with API fallback and throttling. * 1) Check if user already has sufficient balance to claim * 2) If eligible (canTop && balance < toppingAmount), try on-chain top-up (user signs). * 3) Guard against gas > toppingAmount and insufficient gas to publish tx. * 4) If on-chain path fails or cannot publish/sign, fallback to backend /verify/topWallet. * 5) Throttle tops to once per chain per throttleMs via localStorage. */ declare function triggerFaucet({ chainId, account, publicClient, walletClient, faucetAddress, env, throttleMs, }: TriggerFaucetParams): Promise; export { CHAIN_DECIMALS, CITIZEN_SDK_ENVIRONMENTS, CITIZEN_SDK_SUPPORTED_CHAINS, type ChainConfig, type ChainConnectedStatus, type CheckEntitlementOptions, type CheckGenericDailyStatsOptions, type CheckGenericEntitlementOptions, ClaimCustodialSDK, type ClaimEntitlementResult, ClaimSDK, type ClaimSDKOptions, type ClaimTransactionSubmittedCallback, type ClaimTxConfirmCallback, type ContractAddresses, Envs, FALLBACK_CHAIN_PRIORITY, FV_IDENTIFIER_MSG2, type IdentityContract, IdentityCustodialSDK, type IdentityExpiry, type IdentityExpiryData, IdentitySDK, type IdentitySDKOptions, SUPPORTED_CHAIN_IDS, type SdkCapabilityOperation, type SdkCapabilitySummary, type SdkEffect, type SdkRuntimeNeed, type SupportedChainId, SupportedChains$1 as SupportedChains, type TriggerFaucetParams, type TriggerFaucetResult, WALLET_LINK_SECURITY_MESSAGES, type WalletClaimStatus, type WalletLinkAction, type WalletLinkOptions, chainConfigs, checkGenericDailyStats, checkGenericEntitlement, citizenSdkCapabilities, type contractEnv, createRpcUrlIterator, faucetABI, g$ABI, identityV2ABI, initializeIdentityContract, isSupportedChain, triggerFaucet, ubiSchemeV2ABI };