Gas sponsoring

{
  "data": {
    "bytes": "AAADAQ...AAA=",
    "sponsorSignature": "AHq3...Q==",
    "digest": "8nTq...v4Yx",
    "sponsor": "0x...",
    "category": "trophy",
    "gasBudget": "13875000",
    "estimatedGasMist": "9700000",
    "expiresAt": 1793041320000
  }
}

{
  "data": {
    "digest": "8nTq...v4Yx",
    "ok": true,
    "gasUsedMist": "9214880"
  }
}

{
  "error": {
    "code": "not_sponsored",
    "message": "This wallet has enough SUI to pay its own fee"
  }
}

import { bcs } from "@mysten/sui/bcs";
import { SuiGrpcClient } from "@mysten/sui/grpc";
import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
import { Transaction } from "@mysten/sui/transactions";
import { fromBase64, normalizeSuiAddress, toBase64 } from "@mysten/sui/utils";

const API = "https://rare.market/api/v1";
const client = new SuiGrpcClient({ network: "mainnet", baseUrl: "https://fullnode.mainnet.sui.io:443" });

type Category = "trophy" | "trade" | "rescue" | "walrus";

async function post<T>(path: string, body: unknown): Promise<T> {
  const res = await fetch(`${API}${path}`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(body),
  });
  const json = await res.json();
  if (!res.ok) throw Object.assign(new Error(json.error?.message ?? `HTTP ${res.status}`), { code: json.error?.code, status: res.status });
  return json.data as T;
}

/** The sponsored bytes must carry our sender, our kind, and the sponsor as gas owner. */
function checkSponsored(bytes: string, kind: string, sender: string, sponsor: string) {
  const data = bcs.TransactionData.parse(fromBase64(bytes)).V1;
  if (!data) throw new Error("unknown transaction version");
  if (normalizeSuiAddress(data.sender) !== normalizeSuiAddress(sender)) throw new Error("sender changed");
  if (normalizeSuiAddress(data.gasData.owner) !== normalizeSuiAddress(sponsor)) throw new Error("gas owner is not the sponsor");
  if (toBase64(bcs.TransactionKind.serialize(data.kind).toBytes()) !== kind) throw new Error("transaction changed");
}

export async function runSponsored(tx: Transaction, sender: string, category: Category, sign: (bytes: Uint8Array) => Promise<string>) {
  // 1. Kind bytes only. The sponsor's coin pays the gas, so never touch tx.gas.
  tx.setSenderIfNotSet(sender);
  const kind = toBase64(await tx.build({ client, onlyTransactionKind: true }));

  // 2. Ask rare.market to cover the fee.
  const s = await post<{ bytes: string; digest: string; sponsor: string; expiresAt: number }>("/sponsor", { sender, kind, category });
  checkSponsored(s.bytes, kind, sender, s.sponsor);

  // 3. The player signs exactly these bytes.
  const signature = await sign(fromBase64(s.bytes));

  // 4. rare.market adds its signature and submits.
  const r = await post<{ digest: string; ok: boolean; error?: string; gasUsedMist: string }>("/sponsor/execute", { digest: s.digest, signature });
  if (!r.ok) throw new Error(r.error ?? "transaction failed");
  return r.digest;
}

// --- usage: claim a Rare trophy for a player with no SUI ---
const player = Ed25519Keypair.fromSecretKey(process.env.PLAYER_KEY!);
const sender = player.toSuiAddress();

const tx = new Transaction();
// ...add the trophy claim calls here (see /docs/games/trophies)...

try {
  const digest = await runSponsored(tx, sender, "trophy", async (bytes) => (await player.signTransaction(bytes)).signature);
  console.log("claimed, fee covered by rare.market:", digest);
} catch (e) {
  const err = e as Error & { code?: string };
  // not_sponsored, limit_reached, sponsor_unavailable, ...: let the player pay their own fee instead.
  console.log("not sponsored:", err.code, err.message);
}