@stablestation/sponsor

Pay SUI gas fees with stablecoins. This SDK handles transaction preparation, gas estimation, stablecoin payment injection, and sponsor co-signing — your users never need to hold SUI.

Install

pnpm add @stablestation/sponsor @mysten/sui

Quick start

import { SuiGrpcClient } from "@mysten/sui/grpc";
import { Transaction } from "@mysten/sui/transactions";
import { stableStation } from "@stablestation/sponsor";

// 1. Create a SUI client with the StableStation extension
const client = new SuiGrpcClient({ network: "testnet" })
  .$extend(stableStation({
    apiUrl: "https://stablestation.vercel.app",
  }));

// 2. Build your transaction as usual — do NOT set sender, gas, or payment
const tx = new Transaction();
tx.moveCall({
  target: "0xPACKAGE::module::function",
  arguments: [tx.pure.string("hello")],
});

// 3. Prepare: estimates gas, adds stablecoin payment, returns bytes for signing
const prepared = await client.stableStation.prepare({
  transaction: tx,
  sender: userAddress,
  stablecoin: "USDC", // symbol or full coin type
});

// 4. User signs the prepared bytes (any wallet adapter works)
const { signature } = await wallet.signTransaction(prepared.txBytes);

// 5. Execute: API validates, co-signs, and submits on-chain
const result = await client.stableStation.execute(prepared, signature);

console.log(result.digest);    // transaction digest
console.log(result.succeeded); // true if execution succeeded

How it works

The SDK adds two methods to your SUI client via $extend():

prepare() builds the full transaction:

1. Fetches service config from the API (sponsor address, SUI price, stablecoins, markup)
2. Clones your transaction and appends a send_funds stablecoin payment to the sponsor
3. Simulates to measure actual gas cost
4. Rebuilds with the exact payment amount and gas budget
5. Returns txBytes (Uint8Array) for the user to sign

execute(prepared, signature) submits the signed transaction:

1. Sends the signed bytes to the sponsor API
2. API validates (signature + static analysis + simulation), co-signs, and executes on-chain
3. Returns the digest and execution status

API

stableStation(options)

Creates a client extension. Attach it with $extend().

| Option | Type | Description | |--------|------|-------------| | apiUrl | string | Required. StableStation API base URL | | name | string | Extension name (default: "stableStation") | | fetch | typeof fetch | Custom fetch (useful for React Native or testing) |

client.stableStation.config()

Returns the current service configuration:

interface ServiceConfig {
  network: string;
  sponsorAddress: string;
  gasMarkup: number;
  suiPriceUsd: number;
  stablecoins: Record<string, StablecoinConfig>;
}

client.stableStation.prepare(options)

Prepares a sponsored transaction for signing.

| Option | Type | Description | |--------|------|-------------| | transaction | Transaction | Your transaction (do not set sender/gas/payment) | | sender | string | Sender's SUI address | | stablecoin | string | "USDC" or a full coin type string |

Returns:

interface PreparedTransaction {
  txBytes: Uint8Array;    // sign this with the user's wallet
  coinType: string;       // resolved full coin type
  gasBudget: bigint;      // gas budget in MIST
  paymentAmount: bigint;  // stablecoin amount in smallest unit
}

client.stableStation.execute(prepared, signature)

Submits the signed transaction for sponsor co-signing and on-chain execution.

| Argument | Type | Description | |----------|------|-------------| | prepared | PreparedTransaction | Result from prepare() | | signature | string | User's base64 signature from wallet |

Returns:

interface ExecutedTransaction {
  digest: string;         // on-chain transaction digest
  succeeded: boolean;     // whether execution succeeded
  error?: string;         // error message when succeeded is false
  coinType: string;       // resolved full coin type
  gasBudget: bigint;      // gas budget in MIST
  paymentAmount: bigint;  // stablecoin amount in smallest unit
}

Self-hosting

Point apiUrl at your own deployment:

stableStation({ apiUrl: "https://your-api.example.com" })

See the main repo for API deployment instructions.

License

MIT