@dopamint-fun/open-sdk 0.1.0-dev.0 → 0.2.0-dev.0

package/dist/offer.js

@@ -15,6 +15,7 @@ import { signOfferAcceptance } from "./acceptance.js";
 import { AGENT_HTTP_CAPABILITY_HEADER, mintAgentHttpCapability, } from "./agentHttp.js";
 import { fromHex, toHex } from "./bytes.js";
 import { randomBytes } from "node:crypto";
+import { refusalMessage } from "./refusal.js";
 const hexBytes = (value) => fromHex(value.replace(/^0x/, ""));
 async function readJson(url, init) {
     const response = await fetch(url, init);
@@ -36,6 +37,7 @@ function record(raw) {
         state: raw?.state,
         seats,
         acceptedSeats: (raw?.acceptances ?? []).map((entry) => entry.seat),
+        houseSeats: (raw?.house_seats ?? raw?.houseSeats ?? []),
         admission: admissionRaw
             ? {
                 sessionBaseUrl: admissionRaw.session_base_url ?? admissionRaw.sessionBaseUrl,
@@ -52,7 +54,7 @@ function record(raw) {
 export async function readOffer(productUrl, offerId) {
     const { status, json } = await readJson(`${productUrl.replace(/\/$/, "")}/open/v1/playground/matches/${offerId}`);
     if (status !== 200)
-        throw new Error(`offer read refused (${status}): ${JSON.stringify(json)}`);
+        throw new Error(refusalMessage("offer read", status, json));
     return record(json);
 }
 /** Sign and submit this seat's acceptance. Already-accepted is not an error:
@@ -77,13 +79,14 @@ export async function acceptOffer(productUrl, offerId, seat, agent) {
         accepted: true,
         acceptance_nonce: Array.from(signed.acceptanceNonce),
         signature: Array.from(signed.signature),
+        seat_possession_signature: Array.from(signed.seatPossessionSignature),
     });
     const { status, json } = await readJson(`${productUrl.replace(/\/$/, "")}/open/v1/playground/matches/${offerId}/acceptances`, { method: "POST", headers: { "content-type": "application/json" }, body });
     if (status === 200 || status === 201)
         return;
     if (status === 409)
         return;
-    throw new Error(`acceptance refused (${status}): ${JSON.stringify(json)}`);
+    throw new Error(refusalMessage("acceptance", status, json));
 }
 async function admit(productUrl, offerId, agentId, agent) {
     const target = `/open/v1/playground/matches/${offerId}/admit`;
@@ -97,8 +100,28 @@ async function admit(productUrl, offerId, agentId, agent) {
     // either way, and the next read returns the same admission.
     if (status === 200 || status === 201 || status === 409)
         return;
-    throw new Error(`admit refused (${status}): ${JSON.stringify(json)}`);
+    /* A refusal the product marked retryable is a "not yet", and the caller is
+       already in a polling loop that will read the offer and ask again. Treated
+       as a refusal instead, it took the seat out: on a fresh stack two of three
+       seats died on `503 seat_registration_refused` -- the registry had not
+       accepted their registrations on the first pass -- while the third admitted
+       and played the table alone.
+     
+       Only when the product says so, by `next` or, from a product older than
+       `next`, by `retryable`. A `503` that is not retryable is one an
+       operator has to act on (`settlement_funder_exhausted` is the case: a
+       funder's balance cannot pay for the sitting until somebody funds it), and
+       looping on that would spend the timeout hiding the one thing worth
+       reporting. */
+    if (json?.next?.action === "retry" || (status === 503 && json?.retryable === true))
+        return;
+    throw new Error(refusalMessage("admit", status, json));
 }
+/* The states the product will never move off. `expired` belongs here with the
+   other two: a playground offer carries a TTL, and once it lapses no seat can
+   accept and nothing can admit, so a wait that read on past it would spend its
+   whole timeout to report the wrong reason. */
+const ENDED_STATES = new Set(["cancelled", "declined", "expired"]);
 /** Accept this agent's seat, then wait for the offer to admit, admitting it
  *  as soon as every seat has accepted. */
 export async function acceptAndAwaitAdmission(productUrl, offerId, agentId, agent, options = {}) {
@@ -124,13 +147,21 @@ export async function acceptAndAwaitAdmission(productUrl, offerId, agentId, agen
                 executionId,
             };
         }
+        /* Ahead of the admit, because an offer the product has closed is not one
+           to ask about; the state that closed it is the answer the caller wants. */
+        if (ENDED_STATES.has(offer.state))
+            throw new Error(`the offer is ${offer.state}`);
         if (offer.acceptedSeats.length >= offer.seats.length) {
             await admit(productUrl, offerId, agentId, agent);
-            continue;
         }
-        if (offer.state === "cancelled" || offer.state === "declined")
-            throw new Error(`the offer is ${offer.state}`);
-        options.onWaiting?.(offer.acceptedSeats.length, offer.seats.length);
+        else {
+            options.onWaiting?.(offer.acceptedSeats.length, offer.seats.length);
+        }
+        /* The deadline and the sleep are on the admit path too. A retryable
+           refusal reads as a "not yet" and is swallowed above, so a pass that
+           jumped straight back to the read would spin a core against a deployment
+           that answers `503 retryable` forever, and would never give up. The price
+           is one poll interval between admitting and reading the admission back. */
         if (Date.now() >= deadline)
             throw new Error(`offer ${offerId} did not admit; ${offer.acceptedSeats.length} of ${offer.seats.length} seats accepted`);
         await new Promise((resolve) => setTimeout(resolve, pollMs));

package/dist/openTournament.d.ts

@@ -0,0 +1,211 @@
+import { Transaction } from "@mysten/sui/transactions";
+import { type AgentKeypair } from "./keypair.js";
+import { ClientRefusal } from "./refusal.js";
+/** The seat a tournament possession proof is made for. One proof serves every
+ *  table: the settlement registry matches a registration on the key alone. */
+export declare const TOURNAMENT_POSSESSION_SEAT = 1;
+export interface TournamentOverview {
+    tournamentId: string;
+    packageId: string;
+    funder: string;
+    phase: "before_start" | "open" | "matchmaking_closed" | "finalizable" | "finalized";
+    nowMs: number;
+    startMs: number;
+    endMs: number;
+    closeMs: number;
+    level: number;
+    smallBlind: number;
+    bigBlind: number;
+    nextLevelAtMs?: number;
+    chipsPerTicket: number;
+    ticketsPerBundle: number;
+    /** What an agent's transaction needs to name the tournament's objects. */
+    chain?: TournamentChainObjects;
+    [key: string]: unknown;
+}
+/** The shared objects a tournament transaction takes, with the versions they
+ *  were shared at, and the chip's coin type. */
+export interface TournamentChainObjects {
+    tournamentInitialSharedVersion: number;
+    chipTreasuryId: string;
+    chipTreasuryInitialSharedVersion: number;
+    chipType: string;
+}
+export interface TournamentAgentEntry {
+    chipAddress: string;
+    agentId?: string;
+    owner: string;
+    state: "idle" | "queued" | "seated";
+    balance: number;
+    ticketsRedeemed: number;
+    lastSettleMs: number;
+    joinedAtMs: number;
+    tunnelId?: string;
+    runOut: boolean;
+    rank: number;
+    /** The chips the agent's address holds, which `queue_join` must match. */
+    walletBalance?: number;
+}
+/** An owner's entry pass, the NFT its wallet holds. */
+export interface TournamentPass {
+    owner: string;
+    passId: string;
+    playsLeft: number;
+    minted: number;
+}
+/** One of an owner's agents, as the owner route answers it. */
+export interface TournamentOwnerAgent {
+    agentId: string;
+    name?: string;
+    chipAddress: string;
+    playsHeld: number;
+    /** The plays it holds. An agent enters by naming one as a shared object. */
+    plays: TournamentPlay[];
+}
+/** One play, named the way a transaction must name it. */
+export interface TournamentPlay {
+    playId: string;
+    initialSharedVersion: number;
+}
+export interface TournamentOwnerView {
+    owner: string;
+    pass?: TournamentPass;
+    agents: TournamentOwnerAgent[];
+}
+export type TournamentQueueEntry = {
+    state: "not_entered";
+    chipAddress: string;
+} | {
+    state: "idle";
+    chipAddress: string;
+    balance: number;
+} | {
+    state: "queued";
+    chipAddress: string;
+    stack: number;
+    joinedAtMs: number;
+    waiting: number;
+} | {
+    state: "composing";
+    chipAddress: string;
+    stack: number;
+} | {
+    state: "seated";
+    chipAddress: string;
+    offerId?: string;
+    seat?: number;
+    executionId?: string;
+};
+export interface TournamentClient {
+    productUrl: string;
+    agent: AgentKeypair;
+    /** 32 bytes */
+    agentId: Uint8Array;
+    tournamentId: string;
+    /** Injected in tests; the global fetch otherwise. */
+    fetchImpl?: typeof fetch;
+}
+/** A refusal the product named, kept whole so a caller can say why. */
+export declare class TournamentRefusal extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown, what: string);
+    get code(): string | undefined;
+}
+export declare function readTournament(productUrl: string, tournamentId: string, fetchImpl?: typeof fetch): Promise<TournamentOverview>;
+/** The open-entry tournaments the product runs. */
+export declare function listTournaments(productUrl: string, fetchImpl?: typeof fetch): Promise<TournamentOverview[]>;
+/** One of the tournament's retained tables. */
+export interface TournamentMatch {
+    executionId: string;
+    offerId: string;
+    /** When a dispute against this table's tunnel can be closed, read from the
+     *  tunnel. Absent on every table nobody disputed, which is the ordinary
+     *  case. */
+    disputedUntilMs?: number;
+    seats: {
+        seat: number;
+        agentId: string;
+        chipAddress: string;
+    }[];
+}
+/** The tables this tournament has composed, newest state included.
+ *
+ *  The only place `disputedUntilMs` is published: an agent whose table is under
+ *  dispute learns it here or not at all, and the book still shows it seated
+ *  meanwhile. */
+export declare function readTournamentMatches(productUrl: string, tournamentId: string, fetchImpl?: typeof fetch): Promise<TournamentMatch[]>;
+/** When this chip address's table is under dispute, and until when.
+ *
+ *  Unknown counts as no dispute: a read that did not answer is no reason to
+ *  tell an agent its payout is held.
+ */
+export declare function disputeHolding(productUrl: string, tournamentId: string, chipAddress: string, fetchImpl?: typeof fetch): Promise<number | undefined>;
+/** The agent's entry in the chip book, or `null` before its first redeem. */
+export declare function readAgentEntry(productUrl: string, tournamentId: string, chipAddress: string, fetchImpl?: typeof fetch): Promise<TournamentAgentEntry | null>;
+/** An owner's pass, or `null` when the owner has claimed none. */
+export declare function readPass(productUrl: string, tournamentId: string, owner: string, fetchImpl?: typeof fetch): Promise<TournamentPass | null>;
+/** An owner's side: its pass and every agent it has claimed, each with the
+ *  plays it holds. This is where an agent finds the play it enters on. */
+export declare function readOwner(productUrl: string, tournamentId: string, owner: string, fetchImpl?: typeof fetch): Promise<TournamentOwnerView>;
+/** The plays `chipAddress` holds under `owner`, oldest first. */
+export declare function playsHeldBy(productUrl: string, tournamentId: string, owner: string, chipAddress: string, fetchImpl?: typeof fetch): Promise<TournamentPlay[]>;
+/** The agent's possession proof: its key over the seat-1 possession message. */
+export declare function tournamentPossessionSignature(agent: AgentKeypair): Promise<string>;
+/** Present the agent to matchmaking and read where it stands. Cheap and
+ *  idempotent: an agent polls this while it waits. */
+export declare function presentToTournament(client: TournamentClient): Promise<TournamentQueueEntry>;
+export interface JoinPlan {
+    /** Redeem first: the agent has run out and holds a play to spend. */
+    redeem: boolean;
+    /** The play a redeem spends. */
+    play?: TournamentPlay;
+    /** The chips taken from the agent's address: its booked balance, which is
+     *  the dust a redeem burns or the stack `queue_join` escrows. */
+    withdraw: number;
+}
+/** Why `join` refuses to build anything, said before a transaction is sent
+ *  the chain would abort, with the move that follows from it. */
+export declare class JoinRefused extends ClientRefusal {
+}
+/** Decide what `join` sends, from the book and the agent's wallet.
+ *
+ *  `queue_join` takes a coin of exactly the booked balance, and `redeem` burns
+ *  a coin of exactly the booked balance. Chips the agent moved away are not
+ *  lost to the book, only unplayable, so a wallet that differs from the book
+ *  is refused here with the reason rather than on chain without one. */
+export declare function planJoin(overview: TournamentOverview, entry: TournamentAgentEntry | null, 
+/** The plays this agent holds; the first is the one it spends. */
+plays: readonly TournamentPlay[], owner: string | undefined): JoinPlan;
+/** The line an `--until-out` run ends on once matchmaking is over.
+ *
+ *  It used to put the phase after "matchmaking is", which read "matchmaking
+ *  is matchmaking closed" for the phase that says so. The phase is kept as the
+ *  wire spells it, so a reader can branch on it. */
+export declare function matchmakingOverLine(phase: TournamentOverview["phase"], stillQueued: boolean): string;
+/** The transaction `join` sends: optionally redeem, then `queue_join`, in one
+ *  programmable transaction, the minted coin passed straight into the escrow. */
+export declare function joinTransaction(overview: TournamentOverview, plan: JoinPlan, sender: string): Transaction;
+/** The transaction `give-back` sends: the play stays in the world naming
+ *  nobody, so its owner can place it again without a second signature from an
+ *  agent that has already walked away. */
+export declare function giveBackTransaction(overview: TournamentOverview, play: TournamentPlay, sender: string): Transaction;
+/** The transaction `leave` sends: `queue_leave`, and the chips it returns sent
+ *  back to the agent's own address balance. */
+export declare function leaveTransaction(overview: TournamentOverview, sender: string): Transaction;
+export interface SponsoredExecution {
+    digest: string;
+    status: "success" | "failure";
+    error?: string;
+}
+/** Have the product sponsor `tx` and execute it with the agent's signature.
+ *
+ *  The product builds the gas around the agent's transaction kind, the agent
+ *  signs the whole transaction, and the product adds its sponsor signature
+ *  and submits. It refuses any transaction that does more than enter, redeem
+ *  into, or leave this tournament. */
+export declare function sponsorAndExecute(client: TournamentClient, tx: Transaction): Promise<SponsoredExecution>;
+/** The agent's chip address as the book keys it. */
+export declare function chipAddressOf(agent: AgentKeypair): string;
+/** Parse a hex id argument, accepting it with or without `0x`. */
+export declare function tournamentIdArg(value: string): string;

package/dist/openTournament.js

@@ -0,0 +1,337 @@
+/* The open-entry tournament from an agent's side, on its own key.
+ *
+ * Entering is not a request to the product. The agent's own transaction does
+ * it on chain: `queue_join` escrows exactly its booked balance, and when it has
+ * run out, `redeem` in the same transaction burns what is left and mints a
+ * fresh stack from its owner's bundle. The product pays the gas and co-signs
+ * as sponsor; it never holds the chips and cannot sign for the agent.
+ *
+ * What the product does need from the agent is a possession proof of its key,
+ * presented once, so the platform can register the key for settlement before
+ * each table. The same request answers where the agent stands, and names the
+ * offer once it is seated.
+ */
+import { Transaction } from "@mysten/sui/transactions";
+import { AGENT_HTTP_CAPABILITY_HEADER, mintAgentHttpCapability, } from "./agentHttp.js";
+import { seatPossessionMessage } from "./acceptance.js";
+import { fromHex, textBytes, toHex0x } from "./bytes.js";
+import { signRaw } from "./keypair.js";
+import { ClientRefusal, refusalMessage } from "./refusal.js";
+/** The seat a tournament possession proof is made for. One proof serves every
+ *  table: the settlement registry matches a registration on the key alone. */
+export const TOURNAMENT_POSSESSION_SEAT = 1;
+/** The Sui system clock. */
+const CLOCK = "0x6";
+function base(productUrl) {
+    return productUrl.replace(/\/$/, "");
+}
+function tournamentPath(tournamentId, rest = "") {
+    return `/open/v1/tournaments/${tournamentId}${rest}`;
+}
+async function readJson(fetchImpl, url) {
+    const response = await fetchImpl(url);
+    const text = await response.text();
+    return {
+        status: response.status,
+        json: text.length === 0 ? undefined : JSON.parse(text),
+    };
+}
+/** A refusal the product named, kept whole so a caller can say why. */
+export class TournamentRefusal extends Error {
+    status;
+    body;
+    constructor(status, body, what) {
+        super(refusalMessage(what, status, body));
+        this.status = status;
+        this.body = body;
+    }
+    get code() {
+        return this.body?.code;
+    }
+}
+export async function readTournament(productUrl, tournamentId, fetchImpl = fetch) {
+    const { status, json } = await readJson(fetchImpl, `${base(productUrl)}${tournamentPath(tournamentId)}`);
+    if (status !== 200)
+        throw new TournamentRefusal(status, json, "tournament read");
+    return json;
+}
+/** The open-entry tournaments the product runs. */
+export async function listTournaments(productUrl, fetchImpl = fetch) {
+    const { status, json } = await readJson(fetchImpl, `${base(productUrl)}/open/v1/tournaments`);
+    if (status === 404)
+        return [];
+    if (status !== 200)
+        throw new TournamentRefusal(status, json, "tournament list");
+    return json.tournaments;
+}
+/** The tables this tournament has composed, newest state included.
+ *
+ *  The only place `disputedUntilMs` is published: an agent whose table is under
+ *  dispute learns it here or not at all, and the book still shows it seated
+ *  meanwhile. */
+export async function readTournamentMatches(productUrl, tournamentId, fetchImpl = fetch) {
+    const { status, json } = await readJson(fetchImpl, `${base(productUrl)}${tournamentPath(tournamentId)}/matches`);
+    if (status !== 200)
+        throw new TournamentRefusal(status, json, "tournament matches read");
+    return json.matches;
+}
+/** When this chip address's table is under dispute, and until when.
+ *
+ *  Unknown counts as no dispute: a read that did not answer is no reason to
+ *  tell an agent its payout is held.
+ */
+export async function disputeHolding(productUrl, tournamentId, chipAddress, fetchImpl = fetch) {
+    try {
+        const matches = await readTournamentMatches(productUrl, tournamentId, fetchImpl);
+        const mine = matches.find((match) => match.disputedUntilMs !== undefined &&
+            match.seats.some((seat) => seat.chipAddress === chipAddress));
+        return mine?.disputedUntilMs;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The agent's entry in the chip book, or `null` before its first redeem. */
+export async function readAgentEntry(productUrl, tournamentId, chipAddress, fetchImpl = fetch) {
+    const { status, json } = await readJson(fetchImpl, `${base(productUrl)}${tournamentPath(tournamentId, `/agents/${chipAddress}`)}`);
+    if (status === 404 && json?.code === "not_in_tournament")
+        return null;
+    if (status !== 200)
+        throw new TournamentRefusal(status, json, "chip book read");
+    return json;
+}
+/** An owner's pass, or `null` when the owner has claimed none. */
+export async function readPass(productUrl, tournamentId, owner, fetchImpl = fetch) {
+    const { status, json } = await readJson(fetchImpl, `${base(productUrl)}${tournamentPath(tournamentId, `/passes/${owner}`)}`);
+    if (status === 404 && json?.code === "not_in_tournament")
+        return null;
+    if (status !== 200)
+        throw new TournamentRefusal(status, json, "pass read");
+    return json;
+}
+/** An owner's side: its pass and every agent it has claimed, each with the
+ *  plays it holds. This is where an agent finds the play it enters on. */
+export async function readOwner(productUrl, tournamentId, owner, fetchImpl = fetch) {
+    const { status, json } = await readJson(fetchImpl, `${base(productUrl)}${tournamentPath(tournamentId, `/owners/${owner}`)}`);
+    if (status !== 200)
+        throw new TournamentRefusal(status, json, "owner read");
+    return json;
+}
+/** The plays `chipAddress` holds under `owner`, oldest first. */
+export async function playsHeldBy(productUrl, tournamentId, owner, chipAddress, fetchImpl = fetch) {
+    const view = await readOwner(productUrl, tournamentId, owner, fetchImpl);
+    const mine = view.agents.find((agent) => agent.chipAddress.toLowerCase() === chipAddress.toLowerCase());
+    return mine?.plays ?? [];
+}
+/** One capability-signed POST. The signature covers the exact body bytes, so
+ *  they are sent verbatim. */
+async function signedPost(client, target, body) {
+    const payload = textBytes(JSON.stringify(body));
+    const { header } = await mintAgentHttpCapability(client.agent, client.agentId, {
+        method: "POST",
+        requestTarget: target,
+        body: payload,
+    });
+    const response = await (client.fetchImpl ?? fetch)(`${base(client.productUrl)}${target}`, {
+        method: "POST",
+        headers: {
+            [AGENT_HTTP_CAPABILITY_HEADER]: header,
+            "content-type": "application/json",
+        },
+        body: payload,
+    });
+    const text = await response.text();
+    return {
+        status: response.status,
+        json: text.length === 0 ? undefined : JSON.parse(text),
+    };
+}
+/** The agent's possession proof: its key over the seat-1 possession message. */
+export async function tournamentPossessionSignature(agent) {
+    return toHex0x(await signRaw(agent, seatPossessionMessage(TOURNAMENT_POSSESSION_SEAT)));
+}
+/** Present the agent to matchmaking and read where it stands. Cheap and
+ *  idempotent: an agent polls this while it waits. */
+export async function presentToTournament(client) {
+    const { status, json } = await signedPost(client, tournamentPath(client.tournamentId, "/entries"), { seatPossessionSignature: await tournamentPossessionSignature(client.agent) });
+    if (status !== 200)
+        throw new TournamentRefusal(status, json, "tournament entry");
+    return json;
+}
+/** Why `join` refuses to build anything, said before a transaction is sent
+ *  the chain would abort, with the move that follows from it. */
+export class JoinRefused extends ClientRefusal {
+}
+/** Decide what `join` sends, from the book and the agent's wallet.
+ *
+ *  `queue_join` takes a coin of exactly the booked balance, and `redeem` burns
+ *  a coin of exactly the booked balance. Chips the agent moved away are not
+ *  lost to the book, only unplayable, so a wallet that differs from the book
+ *  is refused here with the reason rather than on chain without one. */
+export function planJoin(overview, entry, 
+/** The plays this agent holds; the first is the one it spends. */
+plays, owner) {
+    if (overview.phase !== "open")
+        throw new JoinRefused(`the tournament is ${overview.phase.replace("_", " ")}; redeem and queue join are open from its start until matchmaking closes`, overview.phase === "before_start"
+            ? { action: "wait", until_ms: overview.startMs }
+            : { action: "stop" });
+    if (entry && entry.state !== "idle")
+        throw new JoinRefused(`this agent is already ${entry.state}${entry.state === "seated" ? " at a table" : ""}; an agent plays one table at a time`, {
+            action: "wait",
+            poll: `/open/v1/tournaments/${overview.tournamentId}/agents/${entry.chipAddress}`,
+        });
+    const booked = entry?.balance ?? 0;
+    const wallet = entry?.walletBalance ?? booked;
+    if (entry && wallet !== booked)
+        throw new JoinRefused(`the wallet holds ${wallet} chips but the book holds ${booked}; queue_join and redeem both take exactly the booked balance, so move chips back to this address (or away) until the two agree`, { action: "stop" });
+    const runOut = entry === null || entry.runOut;
+    if (!runOut)
+        return { redeem: false, withdraw: booked };
+    const drawFrom = entry?.owner ?? owner;
+    if (!drawFrom)
+        throw new JoinRefused("this agent has no chips yet: name the owner that hands it plays (--owner 0x...)", { action: "use", command: "dopa-open tournament join --owner 0x<owner>" });
+    const play = plays[0];
+    if (!play)
+        throw new JoinRefused(`this agent has run out and holds no play from ${drawFrom}; ask its owner to hand it one`, { action: "ask_owner", what: "hand_out" });
+    return { redeem: true, play, withdraw: booked };
+}
+/** The line an `--until-out` run ends on once matchmaking is over.
+ *
+ *  It used to put the phase after "matchmaking is", which read "matchmaking
+ *  is matchmaking closed" for the phase that says so. The phase is kept as the
+ *  wire spells it, so a reader can branch on it. */
+export function matchmakingOverLine(phase, stillQueued) {
+    return `out matchmaking has closed (phase ${phase})${stillQueued ? " and no table formed for this agent" : ""}`;
+}
+function requireChain(overview) {
+    if (!overview.chain)
+        throw new Error("this product does not publish the tournament's chain objects, so no transaction can name them");
+    return overview.chain;
+}
+/** The transaction `join` sends: optionally redeem, then `queue_join`, in one
+ *  programmable transaction, the minted coin passed straight into the escrow. */
+export function joinTransaction(overview, plan, sender) {
+    const chain = requireChain(overview);
+    const tx = new Transaction();
+    tx.setSender(sender);
+    const tournament = tx.sharedObjectRef({
+        objectId: overview.tournamentId,
+        initialSharedVersion: chain.tournamentInitialSharedVersion,
+        mutable: true,
+    });
+    const clock = tx.sharedObjectRef({
+        objectId: CLOCK,
+        initialSharedVersion: 1,
+        mutable: false,
+    });
+    const booked = plan.withdraw > 0
+        ? tx.moveCall({
+            target: "0x2::coin::redeem_funds",
+            typeArguments: [chain.chipType],
+            arguments: [tx.withdrawal({ amount: plan.withdraw, type: chain.chipType })],
+        })
+        : tx.moveCall({ target: "0x2::coin::zero", typeArguments: [chain.chipType] });
+    let stack = booked;
+    if (plan.redeem) {
+        if (!plan.play)
+            throw new Error("a redeem names the play it spends");
+        stack = tx.moveCall({
+            target: `${overview.packageId}::tournament::redeem`,
+            arguments: [
+                tournament,
+                tx.sharedObjectRef({
+                    objectId: chain.chipTreasuryId,
+                    initialSharedVersion: chain.chipTreasuryInitialSharedVersion,
+                    mutable: true,
+                }),
+                // Taken by value: the call deletes it, so the reference is mutable.
+                tx.sharedObjectRef({
+                    objectId: plan.play.playId,
+                    initialSharedVersion: plan.play.initialSharedVersion,
+                    mutable: true,
+                }),
+                booked,
+                clock,
+            ],
+        });
+    }
+    tx.moveCall({
+        target: `${overview.packageId}::tournament::queue_join`,
+        arguments: [tournament, stack, clock],
+    });
+    return tx;
+}
+/** The transaction `give-back` sends: the play stays in the world naming
+ *  nobody, so its owner can place it again without a second signature from an
+ *  agent that has already walked away. */
+export function giveBackTransaction(overview, play, sender) {
+    const tx = new Transaction();
+    tx.setSender(sender);
+    tx.moveCall({
+        target: `${overview.packageId}::tournament::give_back`,
+        arguments: [
+            tx.sharedObjectRef({
+                objectId: play.playId,
+                initialSharedVersion: play.initialSharedVersion,
+                mutable: true,
+            }),
+        ],
+    });
+    return tx;
+}
+/** The transaction `leave` sends: `queue_leave`, and the chips it returns sent
+ *  back to the agent's own address balance. */
+export function leaveTransaction(overview, sender) {
+    const chain = requireChain(overview);
+    const tx = new Transaction();
+    tx.setSender(sender);
+    const coin = tx.moveCall({
+        target: `${overview.packageId}::tournament::queue_leave`,
+        arguments: [
+            tx.sharedObjectRef({
+                objectId: overview.tournamentId,
+                initialSharedVersion: chain.tournamentInitialSharedVersion,
+                mutable: true,
+            }),
+        ],
+    });
+    tx.moveCall({
+        target: "0x2::coin::send_funds",
+        typeArguments: [chain.chipType],
+        arguments: [coin, tx.pure.address(sender)],
+    });
+    return tx;
+}
+function base64(bytes) {
+    return Buffer.from(bytes).toString("base64");
+}
+/** Have the product sponsor `tx` and execute it with the agent's signature.
+ *
+ *  The product builds the gas around the agent's transaction kind, the agent
+ *  signs the whole transaction, and the product adds its sponsor signature
+ *  and submits. It refuses any transaction that does more than enter, redeem
+ *  into, or leave this tournament. */
+export async function sponsorAndExecute(client, tx) {
+    const kind = await tx.build({ onlyTransactionKind: true });
+    const sender = client.agent.ownerAddressHex;
+    const prepared = await signedPost(client, tournamentPath(client.tournamentId, "/sponsored-transactions"), { kind: base64(kind), sender });
+    if (prepared.status !== 200)
+        throw new TournamentRefusal(prepared.status, prepared.json, "sponsorship");
+    const transaction = prepared.json.transaction;
+    const { signature } = await client.agent.keypair.signTransaction(Uint8Array.from(Buffer.from(transaction, "base64")));
+    const executed = await signedPost(client, tournamentPath(client.tournamentId, "/sponsored-transactions/execute"), { transaction, signature });
+    if (executed.status !== 200)
+        throw new TournamentRefusal(executed.status, executed.json, "sponsored execution");
+    return executed.json;
+}
+/** The agent's chip address as the book keys it. */
+export function chipAddressOf(agent) {
+    return agent.ownerAddressHex;
+}
+/** Parse a hex id argument, accepting it with or without `0x`. */
+export function tournamentIdArg(value) {
+    const bytes = fromHex(value.replace(/^0x/, ""));
+    if (bytes.length !== 32)
+        throw new Error("a tournament id is 32 bytes of hex");
+    return toHex0x(bytes);
+}