@dopamint-fun/open-sdk 0.2.0-dev.1 → 0.2.0-dev.3

package/dist/agentHttp.js

@@ -13,7 +13,7 @@
  * server reconstructs them from the request it actually received, so there is
  * no restated copy to compare and therefore no comparison to forget.
  */
-import { ByteWriter, frameSigningBytes, fromHex, textBytes, toHex } from "./bytes.js";
+import { ByteReader, ByteWriter, frameSigningBytes, fromHex, textBytes, toHex, } from "./bytes.js";
 import { blake2b256 } from "./crypto.js";
 import { signRaw } from "./keypair.js";
 const AGENT_HTTP_CAPABILITY_DOMAIN = textBytes("dopa_open::agent_http_capability::v1");
@@ -94,20 +94,17 @@ export function decodeAgentHttpHeader(value) {
     const bytes = fromHex(value);
     if (bytes.length !== HEADER_BYTES)
         throw new Error(`capability header must be ${HEADER_BYTES} bytes, got ${bytes.length}`);
-    const readU64 = (offset) => {
-        let out = 0n;
-        for (let index = 0; index < 8; index++)
-            out = (out << 8n) | BigInt(bytes[offset + index]);
-        return out;
-    };
-    return {
-        agentId: bytes.slice(0, 32),
-        agentPublicKey: bytes.slice(32, 64),
-        issuedAtMs: readU64(64),
-        expiresAtMs: readU64(72),
-        nonce: bytes.slice(80, 80 + AGENT_HTTP_CAPABILITY_NONCE_BYTES),
-        signature: bytes.slice(80 + AGENT_HTTP_CAPABILITY_NONCE_BYTES),
+    const reader = new ByteReader(bytes);
+    const capability = {
+        agentId: reader.readFixed(32, "agent id"),
+        agentPublicKey: reader.readFixed(32, "agent public key"),
+        issuedAtMs: reader.readU64("issued_at_ms"),
+        expiresAtMs: reader.readU64("expires_at_ms"),
+        nonce: reader.readFixed(AGENT_HTTP_CAPABILITY_NONCE_BYTES, "nonce"),
+        signature: reader.readFixed(SIGNATURE_BYTES, "signature"),
     };
+    reader.finish();
+    return capability;
 }
 /** Mint and sign one capability, and return the header to send with it.
  *

package/dist/claim.js

@@ -1,6 +1,6 @@
 import { randomBytes } from "node:crypto";
 import { signRaw } from "./keypair.js";
-import { concatBytes, equalBytes, frameSigningBytes, fromHex, textBytes, toHex0x, } from "./bytes.js";
+import { ByteReader, ByteWriter, equalBytes, frameSigningBytes, fromHex, textBytes, toHex0x, } from "./bytes.js";
 /* The agent's half of a claim: an invitation its own key signs.
  *
  * A wallet claims an agent by signing for it in the arena's UI. That proves
@@ -22,16 +22,6 @@ export const AGENT_CLAIM_INVITE_MAX_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
  *  nonce || signature`, every field fixed-width. */
 export const AGENT_CLAIM_INVITE_TOKEN_BYTES = 32 + 32 + 32 + 8 + 8 + 16 + 64;
 const ZERO_OWNER = new Uint8Array(32);
-function u64be(value) {
-    const out = new Uint8Array(8);
-    new DataView(out.buffer).setBigUint64(0, value, false);
-    return out;
-}
-function fixed(bytes, length, what) {
-    if (bytes.length !== length)
-        throw new Error(`${what} must be ${length} bytes, got ${bytes.length}`);
-    return bytes;
-}
 /** `AgentClaimInvite::canonical_payload` -- the framed fields. */
 export function claimInviteCanonicalPayload(invite) {
     if (invite.expiresAtMs <= invite.issuedAtMs)
@@ -41,7 +31,18 @@ export function claimInviteCanonicalPayload(invite) {
         throw new Error("an invitation may stay open for at most a week");
     if (invite.nonce.every((byte) => byte === 0))
         throw new Error("the invitation's nonce must not be all zero");
-    return concatBytes(AGENT_CLAIM_INVITE_DOMAIN, Uint8Array.of(0, CANONICAL_WIRE_VERSION, INVITE_OPERATION), fixed(invite.agentId, 32, "agent id"), invite.owner ? fixed(invite.owner, 32, "owner") : ZERO_OWNER, fixed(invite.agentPublicKey, 32, "agent public key"), u64be(invite.issuedAtMs), u64be(invite.expiresAtMs), fixed(invite.nonce, AGENT_CLAIM_INVITE_NONCE_BYTES, "nonce"));
+    return new ByteWriter()
+        .pushBytes(AGENT_CLAIM_INVITE_DOMAIN)
+        .pushByte(0)
+        .pushByte(CANONICAL_WIRE_VERSION)
+        .pushByte(INVITE_OPERATION)
+        .pushFixed(invite.agentId, 32, "agent id")
+        .pushFixed(invite.owner ?? ZERO_OWNER, 32, "owner")
+        .pushFixed(invite.agentPublicKey, 32, "agent public key")
+        .pushU64(invite.issuedAtMs)
+        .pushU64(invite.expiresAtMs)
+        .pushFixed(invite.nonce, AGENT_CLAIM_INVITE_NONCE_BYTES, "nonce")
+        .bytes();
 }
 /** The bytes the agent's key signs, raw ed25519. */
 export function claimInviteSigningBytes(invite) {
@@ -66,7 +67,15 @@ export async function mintClaimInvite(agent, agentId, options = {}) {
 function claimInviteBytes(invite) {
     if (invite.signature.length !== 64)
         throw new Error("an invitation is encoded only once it is signed");
-    return concatBytes(fixed(invite.agentId, 32, "agent id"), invite.owner ?? ZERO_OWNER, fixed(invite.agentPublicKey, 32, "agent public key"), u64be(invite.issuedAtMs), u64be(invite.expiresAtMs), fixed(invite.nonce, 16, "nonce"), invite.signature);
+    return new ByteWriter()
+        .pushFixed(invite.agentId, 32, "agent id")
+        .pushFixed(invite.owner ?? ZERO_OWNER, 32, "owner")
+        .pushFixed(invite.agentPublicKey, 32, "agent public key")
+        .pushU64(invite.issuedAtMs)
+        .pushU64(invite.expiresAtMs)
+        .pushFixed(invite.nonce, AGENT_CLAIM_INVITE_NONCE_BYTES, "nonce")
+        .pushBytes(invite.signature)
+        .bytes();
 }
 /** The token the link carries and the claim body posts back: 0x-hex.
  *
@@ -115,16 +124,23 @@ export function decodeClaimInvite(token) {
     const bytes = claimInviteTokenBytes(token.trim());
     if (bytes.length !== AGENT_CLAIM_INVITE_TOKEN_BYTES)
         throw new Error(`an invitation token is ${AGENT_CLAIM_INVITE_TOKEN_BYTES} bytes, got ${bytes.length}`);
-    const view = new DataView(bytes.buffer, bytes.byteOffset);
-    const owner = bytes.slice(32, 64);
+    const reader = new ByteReader(bytes);
+    const agentId = reader.readFixed(32, "agent id");
+    const owner = reader.readFixed(32, "owner");
+    const agentPublicKey = reader.readFixed(32, "agent public key");
+    const issuedAtMs = reader.readU64("issued");
+    const expiresAtMs = reader.readU64("expires");
+    const nonce = reader.readFixed(AGENT_CLAIM_INVITE_NONCE_BYTES, "nonce");
+    const signature = reader.readFixed(64, "signature");
+    reader.finish();
     return {
-        agentId: bytes.slice(0, 32),
+        agentId,
         owner: equalBytes(owner, ZERO_OWNER) ? null : owner,
-        agentPublicKey: bytes.slice(64, 96),
-        issuedAtMs: view.getBigUint64(96, false),
-        expiresAtMs: view.getBigUint64(104, false),
-        nonce: bytes.slice(112, 128),
-        signature: bytes.slice(128),
+        agentPublicKey,
+        issuedAtMs,
+        expiresAtMs,
+        nonce,
+        signature,
     };
 }
 /** Where the owner goes to accept: the agent's claim page with the token. */

package/dist/cli.js

@@ -23,7 +23,7 @@ import { claimInviteLink, encodeClaimInvite, encodeClaimInviteCompact, mintClaim
 import { acceptAndAwaitAdmission } from "./offer.js";
 import { playTour, queueUntilSeated } from "./tour.js";
 import { joinRoomWhenComposed, MIN_ROOM_SEATS, openRoom, roomInvitePrompt, } from "./room.js";
-import { disputeHolding, JoinRefused, joinTransaction, leaveTransaction, listTournaments, matchmakingOverLine, planJoin, presentToTournament, readAgentEntry, playsHeldBy, giveBackTransaction, readTournament, sponsorAndExecute, tournamentIdArg, } from "./openTournament.js";
+import { disputeHolding, JoinRefused, joinTransaction, leaveTransaction, listTournaments, matchmakingOverLine, planJoin, presentToTournament, readAgentEntry, readAgentEntrySettled, playsHeldBy, giveBackTransaction, readTournament, sponsorAndExecute, tournamentIdArg, } from "./openTournament.js";
 import { authorityOriginFromSessionBase, buildConsentRequest, digestForPrompt, settlementConsentPath, verifyConsentDisclosure, } from "./settlement.js";
 import { actionSigningBytes, joinSigningBytes, requireSessionVersion, resumeSigningBytes, SESSION_VERSION, } from "./sessionWire.js";
 import { describeNext, refusalMessageFromText } from "./refusal.js";
@@ -1471,8 +1471,16 @@ async function commandTournament(args) {
         return;
     }
     if (verb === "leave") {
-        if (entry?.state !== "queued")
-            fail(`this agent is ${entry?.state ?? "not in the book"}; only a queued agent can leave, and a seated one plays its table out`);
+        /* An agent that queued a moment ago is on chain and not yet in the book,
+           which is read a checkpoint behind it. Refusing on the first read told an
+           agent that had just been printed `queued waiting` that it was not in the
+           book at all, and the refusal's own `next` sent it to join again — which
+           would queue an agent that is already queued. So an absent entry is
+           waited out, briefly, before it is believed. */
+        const settled = entry ??
+            (await readAgentEntrySettled(productUrl, tournamentId, chip));
+        if (settled?.state !== "queued")
+            fail(`this agent is ${settled?.state ?? "not in the book"}; only a queued agent can leave, and a seated one plays its table out`);
         const executed = await sponsorAndExecute(client, leaveTransaction(overview, chip));
         console.log(`left ${executed.digest} ${executed.status}`);
         if (executed.status !== "success")

package/dist/identity.js

@@ -12,6 +12,7 @@
  * bytes. The product parses before it verifies -- it trims each field and
  * lower-cases the handle -- so this signs the parsed form, or the signature
  * is over bytes the store never holds. */
+import { ByteWriter, fromHex, textBytes } from "./bytes.js";
 import { signOwnerAuthenticator } from "./keypair.js";
 import { refusalMessageFromText } from "./refusal.js";
 const IDENTITY_DOMAIN = "dopa_open::agent_identity::v1";
@@ -25,40 +26,20 @@ export function parseIdentityFields(fields) {
         bio: fields.bio?.trim() || null,
     };
 }
-function u64be(value) {
-    const out = new Uint8Array(8);
-    new DataView(out.buffer).setBigUint64(0, BigInt(value));
-    return out;
-}
-function fromHex(value) {
-    const hex = value.replace(/^0x/i, "");
-    const out = new Uint8Array(hex.length / 2);
-    for (let index = 0; index < out.length; index++)
-        out[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
-    return out;
-}
 /** The exact bytes the owning address signs to name an agent. */
 export function canonicalIdentityPayload(edit) {
-    const encoder = new TextEncoder();
-    const domain = encoder.encode(IDENTITY_DOMAIN);
+    const domain = textBytes(IDENTITY_DOMAIN);
     const parsed = parseIdentityFields(edit.fields);
-    const parts = [parsed.name ?? "", parsed.handle ?? "", parsed.bio ?? ""].map((field) => encoder.encode(field));
-    const chunks = [
-        u64be(domain.length),
-        domain,
-        fromHex(edit.agentId),
-        fromHex(edit.owner),
-        ...parts.flatMap((field) => [u64be(field.length), field]),
-        u64be(edit.issuedAtMs),
-        u64be(edit.expiresAtMs),
-    ];
-    const out = new Uint8Array(chunks.reduce((total, chunk) => total + chunk.length, 0));
-    let offset = 0;
-    for (const chunk of chunks) {
-        out.set(chunk, offset);
-        offset += chunk.length;
+    const writer = new ByteWriter()
+        .pushU64(domain.length)
+        .pushBytes(domain)
+        .pushBytes(fromHex(edit.agentId))
+        .pushBytes(fromHex(edit.owner));
+    for (const field of [parsed.name ?? "", parsed.handle ?? "", parsed.bio ?? ""]) {
+        const bytes = textBytes(field);
+        writer.pushU64(bytes.length).pushBytes(bytes);
     }
-    return out;
+    return writer.pushU64(edit.issuedAtMs).pushU64(edit.expiresAtMs).bytes();
 }
 /** Name an agent, as the address that owns it. Answers what the arena stored. */
 export async function nameAgent(args) {
@@ -73,7 +54,7 @@ export async function nameAgent(args) {
         issuedAtMs,
         expiresAtMs,
     }));
-    const agentId = `0x${args.agentId.replace(/^0x/i, "")}`;
+    const agentId = `0x${args.agentId.replace(/^0x/, "")}`;
     const response = await fetchImpl(`${args.productUrl.replace(/\/$/, "")}/open/v1/agents/${agentId}/identity`, {
         method: "PUT",
         headers: { "content-type": "application/json" },

package/dist/index.d.ts

@@ -17,5 +17,5 @@ export { handEquity, requiredEquity, cardCode, type HandEquity, type HandEquityO
 export { cardIndex, handCategory, scoreHand, HAND_CATEGORIES, RANK_ORDER, SUIT_ORDER, type BestFive, type HandCategory, } from "./handRank.js";
 export { DEFAULT_SEAT_STATE_FILE, loadSeatState, saveSeatState, type SeatSessionState, } from "./seatState.js";
 export { newSeatState, openTurn, submitTurn, type SeatStateCheckpoint, type SeatTurnOutcome, type SeatTurnPosition, } from "./seatTurn.js";
-export { chipAddressOf, joinTransaction, leaveTransaction, listTournaments, planJoin, presentToTournament, readAgentEntry, readPass, readOwner, playsHeldBy, giveBackTransaction, readTournament, sponsorAndExecute, tournamentIdArg, tournamentPossessionSignature, JoinRefused, TournamentRefusal, TOURNAMENT_POSSESSION_SEAT, type JoinPlan, type SponsoredExecution, type TournamentAgentEntry, type TournamentPass, type TournamentPlay, type TournamentOwnerView, type TournamentOwnerAgent, type TournamentChainObjects, type TournamentClient, type TournamentOverview, type TournamentQueueEntry, } from "./openTournament.js";
+export { chipAddressOf, joinTransaction, leaveTransaction, listTournaments, planJoin, presentToTournament, readAgentEntry, readAgentEntrySettled, BOOK_CATCHES_UP_MS, readPass, readOwner, playsHeldBy, giveBackTransaction, readTournament, sponsorAndExecute, tournamentIdArg, tournamentPossessionSignature, JoinRefused, TournamentRefusal, TOURNAMENT_POSSESSION_SEAT, type JoinPlan, type SponsoredExecution, type TournamentAgentEntry, type TournamentPass, type TournamentPlay, type TournamentOwnerView, type TournamentOwnerAgent, type TournamentChainObjects, type TournamentClient, type TournamentOverview, type TournamentQueueEntry, } from "./openTournament.js";
 export { ClientRefusal, describeNext, refusalLines, refusalMessage, refusalMessageFromText, type RefusalBody, type RefusalNext, } from "./refusal.js";

package/dist/index.js

@@ -29,5 +29,5 @@ export { handEquity, requiredEquity, cardCode, } from "./equity.js";
 export { cardIndex, handCategory, scoreHand, HAND_CATEGORIES, RANK_ORDER, SUIT_ORDER, } from "./handRank.js";
 export { DEFAULT_SEAT_STATE_FILE, loadSeatState, saveSeatState, } from "./seatState.js";
 export { newSeatState, openTurn, submitTurn, } from "./seatTurn.js";
-export { chipAddressOf, joinTransaction, leaveTransaction, listTournaments, planJoin, presentToTournament, readAgentEntry, readPass, readOwner, playsHeldBy, giveBackTransaction, readTournament, sponsorAndExecute, tournamentIdArg, tournamentPossessionSignature, JoinRefused, TournamentRefusal, TOURNAMENT_POSSESSION_SEAT, } from "./openTournament.js";
+export { chipAddressOf, joinTransaction, leaveTransaction, listTournaments, planJoin, presentToTournament, readAgentEntry, readAgentEntrySettled, BOOK_CATCHES_UP_MS, readPass, readOwner, playsHeldBy, giveBackTransaction, readTournament, sponsorAndExecute, tournamentIdArg, tournamentPossessionSignature, JoinRefused, TournamentRefusal, TOURNAMENT_POSSESSION_SEAT, } from "./openTournament.js";
 export { ClientRefusal, describeNext, refusalLines, refusalMessage, refusalMessageFromText, } from "./refusal.js";

package/dist/openTournament.d.ts

@@ -143,6 +143,28 @@ export declare function readTournamentMatches(productUrl: string, tournamentId:
 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>;
+/** How long a book read waits for a join that has just landed.
+ *
+ *  The book is the chain's, read a checkpoint behind it: an agent whose
+ *  `queue_join` succeeded a moment ago is on chain and not yet in the book.
+ *  Measured at about a second on a local stack; this is generous enough to
+ *  cover a slower one and short enough that an agent that really is absent is
+ *  told so rather than left waiting. */
+export declare const BOOK_CATCHES_UP_MS = 8000;
+/** The agent's entry, waited for while the book catches up with the chain.
+ *
+ *  For a caller that has just been told its join landed. A plain
+ *  `readAgentEntry` answering `null` in that window is not "this agent never
+ *  queued" — it is "the book has not seen the queue join yet", and the two are
+ *  worth telling apart before refusing somebody. Absent for the whole bound is
+ *  the first answer, and this returns `null` for it. */
+export declare function readAgentEntrySettled(productUrl: string, tournamentId: string, chipAddress: string, options?: {
+    boundMs?: number;
+    pollMs?: number;
+    fetchImpl?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}): 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

package/dist/openTournament.js

@@ -100,6 +100,37 @@ export async function readAgentEntry(productUrl, tournamentId, chipAddress, fetc
         throw new TournamentRefusal(status, json, "chip book read");
     return json;
 }
+/** How long a book read waits for a join that has just landed.
+ *
+ *  The book is the chain's, read a checkpoint behind it: an agent whose
+ *  `queue_join` succeeded a moment ago is on chain and not yet in the book.
+ *  Measured at about a second on a local stack; this is generous enough to
+ *  cover a slower one and short enough that an agent that really is absent is
+ *  told so rather than left waiting. */
+export const BOOK_CATCHES_UP_MS = 8_000;
+/** The agent's entry, waited for while the book catches up with the chain.
+ *
+ *  For a caller that has just been told its join landed. A plain
+ *  `readAgentEntry` answering `null` in that window is not "this agent never
+ *  queued" — it is "the book has not seen the queue join yet", and the two are
+ *  worth telling apart before refusing somebody. Absent for the whole bound is
+ *  the first answer, and this returns `null` for it. */
+export async function readAgentEntrySettled(productUrl, tournamentId, chipAddress, options = {}) {
+    const boundMs = options.boundMs ?? BOOK_CATCHES_UP_MS;
+    const pollMs = options.pollMs ?? 1_000;
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ??
+        ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const deadline = now() + boundMs;
+    for (;;) {
+        const entry = await readAgentEntry(productUrl, tournamentId, chipAddress, options.fetchImpl ?? fetch);
+        if (entry)
+            return entry;
+        if (now() >= deadline)
+            return null;
+        await sleep(pollMs);
+    }
+}
 /** 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}`)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dopamint-fun/open-sdk",
-  "version": "0.2.0-dev.1",
+  "version": "0.2.0-dev.3",
   "description": "DOPA-OPEN client SDK: generate and hold your own agent key, sign registrations, and play a Participant Session",
   "license": "Apache-2.0",
   "repository": {