npm package: @stablestation/sponsor
Description: Pay SUI gas fees with stablecoins — client SDK for StableStation
Latest version: 0.2.1

# @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

```bash
pnpm add @stablestation/sponsor @mysten/sui
```

## Quick start

```ts
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:

```ts
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:

```ts
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:

```ts
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:

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

See the [main repo](https://github.com/stablestation/stablestation) for API deployment instructions.

## License

MIT