Zebec SUI Faucet SDK

An SDK for interacting with the Zebec SUI faucet Move contract. It provides a typed, ergonomic TypeScript interface to query faucet state, request USDC tokens, manage withdrawal profiles, and perform administrative operations.

Installation

npm install @zebec-fintech/sui-faucet-sdk

Peer dependencies (required):

npm install @mysten/sui @mysten/bcs

Quick Start

import { SuiClient, getFullnodeUrl } from "@mysten/sui/client";
import { SuiFaucetService, SuiFaucetPackageInfo } from "@zebec-fintech/sui-faucet-sdk";

const network = "testnet";
const url = getFullnodeUrl(network);

const suiClient = new SuiClient({ url });
const packageInfo = new SuiFaucetPackageInfo(network);

// Provide a wallet that satisfies the WalletInterface
const wallet = {
  address: "<wallet-address>",
  signTransaction: async ({ transaction }) => {
    // Return { bytes, signature }
  },
};

const service = await SuiFaucetService.create(packageInfo, suiClient, wallet);

SuiFaucetService

The main entry point for all faucet interactions. It is instantiated via the static create factory, which resolves network-specific object IDs and coin metadata automatically.

Constructor

new SuiFaucetService(
  packageInfo: SuiFaucetPackageInfo,
  suiClient: ClientWithCoreApi,
  faucetConfigObjectId: SuiAddress,
  usdcCoinType: string,
  usdcCoinMetadata: CoinMetadata,
  wallet: WalletInterface,
)

static async create(...)

Factory method that bootstraps the service for a given network.

static async create(
  packageInfo: SuiFaucetPackageInfo,
  suiClient: ClientWithCoreApi,
  wallet: WalletInterface,
): Promise<SuiFaucetService>

Read Methods

getFaucetConfig()

Returns the on-chain faucet configuration object with human-readable balances and amounts.

async getFaucetConfig(): Promise<SuiFaucetConfig>

SuiFaucetConfig

| Property | Type | Description | |----------------------|----------------|--------------------------------------------------| | id | SuiAddress | Object ID of the faucet config shared object. | | version | NumberString | Current contract version. | | admin | SuiAddress | Address of the faucet admin. | | usdcAddress | SuiAddress | Address of the USDC coin type being distributed. | | amountPerRequest | DecimalString| Amount of USDC dispensed per request (human-readable). | | faucetCooldownPeriod| NumberString| Cooldown between withdrawals in milliseconds.| | balance | DecimalString| Current USDC balance held by the faucet. |

getWithdrawalRecord(params?)

Fetches the FaucetWithdrawalRecord object owned by a user. Throws if no record exists.

async getWithdrawalRecord(params?: { user: SuiAddress }): Promise<SuiFaucetWithdrawalRecord>

SuiFaucetWithdrawalRecord

| Property | Type | Description | |-----------------------|----------|--------------------------------------------| | id | string | Object ID of the withdrawal record. | | withdrawalTimestamp | bigint | Last withdrawal time in milliseconds. |

If params.user is omitted, the record for the connected wallet is returned.

Write Methods

All write methods return a SuiTransactionPayload instance. Call .execute() on it to sign and submit the transaction.

createUserWithdrawalProfile(params?)

Creates a new FaucetWithdrawalRecord object for the given user. This record is required before the user can call getTokenFromFaucet.

async createUserWithdrawalProfile(params?: { user: SuiAddress }): Promise<SuiTransactionPayload>

Example

const payload = await service.createUserWithdrawalProfile();
const result = await payload.execute();
console.log("tx digest:", result.digest);

getTokenFromFaucet()

Requests USDC from the faucet. The connected wallet must already own a FaucetWithdrawalRecord.

async getTokenFromFaucet(): Promise<SuiTransactionPayload>

Example

const payload = await service.getTokenFromFaucet();
const result = await payload.execute();
console.log("tx digest:", result.digest);

refillFaucet(params)

Deposits USDC into the faucet's shared balance. Anyone can call this.

async refillFaucet(params: { amount: string | number }): Promise<SuiTransactionPayload>

| Parameter | Type | Description | |-----------|------------------|----------------------------------------| | amount | string \| number | Human-readable USDC amount to deposit. |

Example

const payload = await service.refillFaucet({ amount: "100" });
const result = await payload.execute();

Admin Methods

These methods require the connected wallet to own the single AdminCap object for the faucet.

updateUsdcAddress(params)

Updates the USDC coin type address in the faucet config.

async updateUsdcAddress(params: { newUsdcAddress: SuiAddress }): Promise<SuiTransactionPayload>

Example

const payload = await service.updateUsdcAddress({ newUsdcAddress: "0x..." });
const result = await payload.execute();

updateAmountPerRequest(params)

Updates how much USDC is dispensed per getTokenFromFaucet call.

async updateAmountPerRequest(params: { newAmountPerRequest: string | number }): Promise<SuiTransactionPayload>

| Parameter | Type | Description | |-----------------------|------------------|----------------------------------------| | newAmountPerRequest | string \| number | New human-readable amount per request. |

Example

const payload = await service.updateAmountPerRequest({ newAmountPerRequest: "500" });
const result = await payload.execute();

updateFaucetCooldownPeriod(params)

Updates the cooldown period between withdrawals.

async updateFaucetCooldownPeriod(params: { newCooldownPeriod: string | number }): Promise<SuiTransactionPayload>

| Parameter | Type | Description | |----------------------|------------------|--------------------------------------| | newCooldownPeriod | string \| number | New cooldown in milliseconds. |

Example

const payload = await service.updateFaucetCooldownPeriod({
  newCooldownPeriod: 8 * 60 * 60 * 1000, // 8 hours
});
const result = await payload.execute();

migrate()

Executes a contract version migration. Requires AdminCap.

async migrate(): Promise<SuiTransactionPayload>

Example

const payload = await service.migrate();
const result = await payload.execute();

SuiTransactionPayload

A thin wrapper around a Sui Transaction that encapsulates signing and execution logic.

execute(options?)

Builds, signs, and executes the transaction, then waits for finality.

async execute(options?: {
  signer?: Signer;
  signal?: AbortSignal;
}): Promise<TransactionResult<object>>

| Option | Type | Description | |----------|--------------|---------------------------------------------------------------------------| | signer | Signer | Optional @mysten/sui/cryptography signer. Used if the wallet has no signTransaction. | | signal | AbortSignal| Optional abort signal to cancel the request. |

Example

const payload = await service.getTokenFromFaucet();
const result = await payload.execute({ signal: AbortSignal.timeout(30_000) });
console.log("status:", result.digest);

SuiFaucetPackageInfo

Resolves network-specific package addresses and module names.

import { SuiFaucetPackageInfo } from "@zebec-fintech/sui-faucet-sdk";

const packageInfo = new SuiFaucetPackageInfo("testnet");
console.log(packageInfo.address); // "0x..."
console.log(packageInfo.module);  // "zebec_sui_faucet"

| Property | Type | Description | |-----------|--------------|---------------------------------------| | network | SuiNetwork | One of mainnet, testnet, devnet.| | address | string | Move package address on that network. | | module | string | Move module name (zebec_sui_faucet).|

Types

WalletInterface

The minimal shape required for a wallet to interact with the SDK.

interface WalletInterface {
  address: string;
  signTransaction?: SuiSignTransactionMethod;
}

SuiSignTransactionMethod

type SuiSignTransactionMethod = (
  input: SuiSignTransactionInput,
) => Promise<SuiSignTransactionOutput>;

SuiSignTransactionInput

interface SuiSignTransactionInput {
  transaction: Transaction | string;
}

SuiSignTransactionOutput

interface SuiSignTransactionOutput {
  bytes: string;
  signature: string;
}

Utility Types

| Type | Alias | Description | |------------------|---------|-----------------------------------------------------| | SuiNetwork | "mainnet" \| "testnet" \| "devnet" | Supported Sui networks. | | SuiAddress | string| Move object or account address. | | DecimalString | string| Human-readable decimal value (e.g. "100.5"). | | NumberString | string| Numeric value represented as a string. |

Utilities

createSuiSignTransactionMethodFromSigner(signer, suiClient?)

Adapts a raw @mysten/sui/cryptography Signer into the SuiSignTransactionMethod shape expected by the SDK.

import { createSuiSignTransactionMethodFromSigner } from "@zebec-fintech/sui-faucet-sdk";

const signTransaction = createSuiSignTransactionMethodFromSigner(mySigner, suiClient);

getCoinDecimals(client, coinType)

Fetches (with local caching) the decimal precision for a given coin type.

import { getCoinDecimals } from "@zebec-fintech/sui-faucet-sdk";

const decimals = await getCoinDecimals(suiClient, coinType);

Constants

Error Codes

The following Move abort codes may be returned by the contract:

| Constant | Code | Meaning | |---------------------------------------------|------|--------------------------------------------| | FAUCET_ERROR_INSUFFICIENT_BALANCE | 0 | Faucet does not have enough USDC to fulfill the request. | | FAUCET_ERROR_NOT_ADMIN | 1 | Caller does not own the AdminCap. | | FAUCET_ERROR_WRONG_VERSION | 2 | Contract version mismatch during migration.| | FAUCET_ERROR_NOT_UPGRADE | 3 | Migration called when no upgrade is pending.| | FAUCET_ERROR_DAILY_WITHDRAWAL_LIMIT_EXCEEDED| 4| User has exceeded the withdrawal limit. | | FAUCET_ERROR_INVALID_USDC_ADDRESS | 5 | Provided USDC address is invalid. |

Network Defaults

The SDK ships with hard-coded object IDs for known deployments:

• FAUCET_PACKAGE_ADDRESS – Move package address per network.
• FAUCET_CONFIG_OBJECT_ID – Shared FaucetConfig object ID per network.
• FAUCET_USDC_COIN_TYPE – Coin type string per network.
• FAUCET_ADMIN_CAP_STRUCT_TYPE – Fully-qualified AdminCap type per network.
• FAUCET_WITHDRAWAL_RECORD_STRUCT_TYPE – Fully-qualified FaucetWithdrawalRecord type per network.

Note: devnet and mainnet addresses are currently placeholders. Update them after deployment.

License

MIT