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

package/README.md

@@ -24,7 +24,14 @@ signatures, not whether this package is used. Allowed dependencies:
 - `channel.ts` — the npm channel-to-install mapping every teaching surface
   reads (`prod` = bare install, `dev`/`canary` = dist tags, local tarball
   override).
-- `dopa-open` CLI — `keygen`, `address`, `register`, `play`, `consent`, `sign`.
+- `openTournament.ts` — the open-entry tournament on the agent's own key:
+  `readTournament` / `readAgentEntry` / `readBundle`, `planJoin` (which refuses
+  a join the chain would abort, and says why), `joinTransaction` /
+  `leaveTransaction`, `presentToTournament` (the possession proof matchmaking
+  needs), and `sponsorAndExecute`, which has the product pay the gas and
+  co-sign as gas owner.
+- `dopa-open` CLI — `keygen`, `address`, `register`, `play`, `consent`, `sign`,
+  and `tournament status | join | leave`.
 
 ## Parity
 

package/dist/acceptance.d.ts

@@ -16,9 +16,15 @@ export interface OfferAcceptance {
     acceptanceNonce: Uint8Array;
 }
 export declare function offerAcceptanceCanonicalPayload(acceptance: OfferAcceptance): Uint8Array;
+export declare function localEvidenceHash(seat: number): Uint8Array;
+/** The exact bytes a seat key signs to prove possession to the settlement
+ *  registry on chain. */
+export declare function seatPossessionMessage(seat: number): Uint8Array;
 export declare function offerAcceptanceSigningBytes(acceptance: OfferAcceptance): Uint8Array;
 export interface SignedOfferAcceptance extends OfferAcceptance {
     /** 64 bytes */
     signature: Uint8Array;
+    /** 64 bytes: this key over `seatPossessionMessage(seat)`. */
+    seatPossessionSignature: Uint8Array;
 }
 export declare function signOfferAcceptance(agent: AgentKeypair, acceptance: OfferAcceptance): Promise<SignedOfferAcceptance>;

package/dist/acceptance.js

@@ -13,6 +13,11 @@
 import { ByteWriter, frameSigningBytes, textBytes } from "./bytes.js";
 import { signRaw } from "./keypair.js";
 const OFFER_ACCEPTANCE_DOMAIN = textBytes("dopa_open::offer_acceptance::v1");
+/* The settlement registry's possession domain, baked into the deployed
+ * `attestation_registry` Move package. Byte-identical to
+ * `SEAT_KEY_POSSESSION_DOMAIN` in `dopa_open_api`; `acceptance.test.ts` pins
+ * the whole message against a Rust-generated vector. */
+const SEAT_KEY_POSSESSION_DOMAIN = textBytes("dopan180/key-possession-v1");
 const CANONICAL_WIRE_VERSION = 1;
 const OFFER_ACCEPTANCE_OPERATION = 5;
 export const ACCEPTANCE_NONCE_BYTES = 32;
@@ -37,12 +42,41 @@ export function offerAcceptanceCanonicalPayload(acceptance) {
         .pushFixed(acceptance.acceptanceNonce, ACCEPTANCE_NONCE_BYTES, "acceptance nonce")
         .bytes();
 }
+/* The document the registry records for a seat: a tag byte, the seat index as
+ * a little-endian u64, zero-padded to 32. No timestamp and no nonce, so it is
+ * fixed for a seat - which is what lets the platform resubmit one signature
+ * later with a fresh document time instead of asking the agent again. */
+export function localEvidenceHash(seat) {
+    if (!Number.isInteger(seat) || seat < 1 || seat > 0xff)
+        throw new RangeError("seat must be a 1-based byte index");
+    const out = new Uint8Array(32);
+    out[0] = 0x90;
+    new DataView(out.buffer).setBigUint64(1, BigInt(seat), true);
+    return out;
+}
+/** The exact bytes a seat key signs to prove possession to the settlement
+ *  registry on chain. */
+export function seatPossessionMessage(seat) {
+    const hash = localEvidenceHash(seat);
+    const out = new Uint8Array(SEAT_KEY_POSSESSION_DOMAIN.length + hash.length);
+    out.set(SEAT_KEY_POSSESSION_DOMAIN, 0);
+    out.set(hash, SEAT_KEY_POSSESSION_DOMAIN.length);
+    return out;
+}
 export function offerAcceptanceSigningBytes(acceptance) {
     return frameSigningBytes(OFFER_ACCEPTANCE_DOMAIN, offerAcceptanceCanonicalPayload(acceptance));
 }
+/* Two signatures by one key under two domains. The second is the artefact the
+ * on-chain settlement registry needs, and only this key can make it: the
+ * platform submits the registration and pays its gas, but `register_local`
+ * authorizes on this signature alone, so it can neither forge one nor aim one
+ * at another key. Sent at acceptance rather than at settlement because the
+ * tunnel funds at admit - a seat that turns out to be unregistrable after that
+ * has already committed the stake. */
 export async function signOfferAcceptance(agent, acceptance) {
     return {
         ...acceptance,
         signature: await signRaw(agent, offerAcceptanceSigningBytes(acceptance)),
+        seatPossessionSignature: await signRaw(agent, seatPossessionMessage(acceptance.seat)),
     };
 }

package/dist/channel.d.ts

@@ -1,5 +1,5 @@
 export declare const PACKAGE_NAME = "@dopamint-fun/open-sdk";
-export type ReleaseChannel = "canary" | "dev" | "prod";
+export type ReleaseChannel = "dev" | "prod";
 export declare const RELEASE_CHANNELS: readonly ReleaseChannel[];
 /** The npm dist-tag a channel publishes under and installs from. */
 export declare function channelDistTag(channel: ReleaseChannel): string;
@@ -22,9 +22,10 @@ export declare function resolveChannel(raw: string | undefined): ReleaseChannel;
  *
  *  `resolveChannel` treats an unset value as prod on purpose: the bare install
  *  is the safe default for a deployment that never says otherwise. That default
- *  is also how the canary stack came to serve `npm install @dopamint-fun/open-sdk`
- *  — an install of a package that was not on the registry — to every agent
- *  that read its skill: nobody had set the variable, and nothing said so.
+ *  is also how a non-production stack came to serve `npm install
+ *  @dopamint-fun/open-sdk` — an install of a package that was not on the
+ *  registry — to every agent that read its skill: nobody had set the
+ *  variable, and nothing said so.
  *
  *  So a deployment that names a non-production environment has to name a
  *  channel too. Production keeps the default, because there the default is
@@ -33,6 +34,6 @@ export declare function resolveChannel(raw: string | undefined): ReleaseChannel;
 export declare function resolveDeployedChannel(channelRaw: string | undefined, deployEnvironment: string | undefined): ReleaseChannel;
 /** Whether a package version belongs on a channel - what the publish script
  *  enforces before it will pass `--tag`. Prod takes stable semver only; dev
- *  and canary take only their own prerelease identifier, so a tag and a
- *  version can never disagree about what a build is. */
+ *  takes only its own prerelease identifier, so a tag and a version can never
+ *  disagree about what a build is. */
 export declare function versionMatchesChannel(version: string, channel: ReleaseChannel): boolean;

package/dist/channel.js

@@ -1,9 +1,16 @@
-/* Release channels: one package name, three npm dist-tags.
+/* Release channels: one package name, two npm dist-tags.
  *
- * canary, dev and prod are the same package at different maturities, selected
- * by tag rather than by name - a name suffix would fork the install line and
- * every document teaching it. Prod rides `latest` so the bare install is
- * production; the other two are opt-in by tag.
+ * dev and prod are the same package at two maturities, selected by tag rather
+ * than by name - a name suffix would fork the install line and every document
+ * teaching it. Prod rides `latest` so the bare install is production; dev is
+ * opt-in by tag.
+ *
+ * Two channels, two environments, one branch each: `dev` ships from `dev`,
+ * `prod` ships from `main`. There was a third, `canary`, and it is gone. A
+ * channel is a promise that some version is published under that tag, and
+ * nobody was keeping it: that stack spent months teaching an install line for
+ * a tag that held nothing. Anything that is not production teaches `dev`, so
+ * another stack needs no third name here.
  *
  * This module is the single owner of the channel-to-install mapping. The
  * skill serving plugin, the playground connect panel, and the SDK skill all
@@ -11,11 +18,7 @@
  * another elsewhere.
  */
 export const PACKAGE_NAME = "@dopamint-fun/open-sdk";
-export const RELEASE_CHANNELS = [
-    "canary",
-    "dev",
-    "prod",
-];
+export const RELEASE_CHANNELS = ["dev", "prod"];
 /** The npm dist-tag a channel publishes under and installs from. */
 export function channelDistTag(channel) {
     return channel === "prod" ? "latest" : channel;
@@ -55,9 +58,10 @@ export function resolveChannel(raw) {
  *
  *  `resolveChannel` treats an unset value as prod on purpose: the bare install
  *  is the safe default for a deployment that never says otherwise. That default
- *  is also how the canary stack came to serve `npm install @dopamint-fun/open-sdk`
- *  — an install of a package that was not on the registry — to every agent
- *  that read its skill: nobody had set the variable, and nothing said so.
+ *  is also how a non-production stack came to serve `npm install
+ *  @dopamint-fun/open-sdk` — an install of a package that was not on the
+ *  registry — to every agent that read its skill: nobody had set the
+ *  variable, and nothing said so.
  *
  *  So a deployment that names a non-production environment has to name a
  *  channel too. Production keeps the default, because there the default is
@@ -68,15 +72,15 @@ export function resolveDeployedChannel(channelRaw, deployEnvironment) {
     if (environment && environment !== "production" && !channelRaw?.trim()) {
         throw new Error(`DOPA_OPEN_SDK_CHANNEL is unset on the ${environment} deployment. Unset ` +
             `means prod, and a ${environment} stack teaching the production install ` +
-            `line is how canary served an install nobody could run. Set it to one ` +
+            `line is how a stack came to serve an install nobody could run. Set it to one ` +
             `of ${RELEASE_CHANNELS.join(", ")} on the dopamint-arena-${environment} environment.`);
     }
     return resolveChannel(channelRaw);
 }
 /** Whether a package version belongs on a channel - what the publish script
  *  enforces before it will pass `--tag`. Prod takes stable semver only; dev
- *  and canary take only their own prerelease identifier, so a tag and a
- *  version can never disagree about what a build is. */
+ *  takes only its own prerelease identifier, so a tag and a version can never
+ *  disagree about what a build is. */
 export function versionMatchesChannel(version, channel) {
     const stable = /^\d+\.\d+\.\d+$/;
     if (channel === "prod")

package/dist/claim.d.ts

@@ -32,8 +32,26 @@ export declare function mintClaimInvite(agent: AgentKeypair, agentId: Uint8Array
     ttlMs?: number;
     nonce?: Uint8Array;
 }): Promise<ClaimInvite>;
-/** The token the link carries and the claim body posts back: 0x-hex. */
+/** The token the link carries and the claim body posts back: 0x-hex.
+ *
+ *  Kept because it is what already-minted links and the Rust vectors are
+ *  written in. New links take the base64url form below, which is the same
+ *  bytes 130 characters shorter. */
 export declare function encodeClaimInvite(invite: ClaimInvite): string;
+/** The same token, base64url, which is what a link should carry.
+ *
+ *  A claim link is pasted into chat, a terminal and a browser bar, and hex
+ *  spends two characters on every byte to say it in an alphabet nobody reads.
+ *  192 bytes is 386 characters of `0x`-hex and 256 of base64url, and the
+ *  saving is the whole of the difference between a link and a wall of text.
+ *  Nothing signed changes: this is the encoding of the token, not the token.
+ *
+ *  base64url specifically, not base64: `+` and `/` are not safe in a query
+ *  string, and `=` padding is dropped because a fixed-width token needs none
+ *  to be read back. */
+export declare function encodeClaimInviteCompact(invite: ClaimInvite): string;
+/** Read either encoding. A link minted before the compact form still works,
+ *  and a reader never has to be told which one it is holding. */
 export declare function decodeClaimInvite(token: string): ClaimInvite;
 /** Where the owner goes to accept: the agent's claim page with the token. */
 export declare function claimInviteLink(arenaOrigin: string, agentIdHex: string, token: string): string;

package/dist/claim.js

@@ -62,14 +62,57 @@ export async function mintClaimInvite(agent, agentId, options = {}) {
     invite.signature = await signRaw(agent, claimInviteSigningBytes(invite));
     return invite;
 }
-/** The token the link carries and the claim body posts back: 0x-hex. */
-export function encodeClaimInvite(invite) {
+/** The 192 bytes a token carries, in order. */
+function claimInviteBytes(invite) {
     if (invite.signature.length !== 64)
         throw new Error("an invitation is encoded only once it is signed");
-    return toHex0x(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 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);
+}
+/** The token the link carries and the claim body posts back: 0x-hex.
+ *
+ *  Kept because it is what already-minted links and the Rust vectors are
+ *  written in. New links take the base64url form below, which is the same
+ *  bytes 130 characters shorter. */
+export function encodeClaimInvite(invite) {
+    return toHex0x(claimInviteBytes(invite));
+}
+/** The same token, base64url, which is what a link should carry.
+ *
+ *  A claim link is pasted into chat, a terminal and a browser bar, and hex
+ *  spends two characters on every byte to say it in an alphabet nobody reads.
+ *  192 bytes is 386 characters of `0x`-hex and 256 of base64url, and the
+ *  saving is the whole of the difference between a link and a wall of text.
+ *  Nothing signed changes: this is the encoding of the token, not the token.
+ *
+ *  base64url specifically, not base64: `+` and `/` are not safe in a query
+ *  string, and `=` padding is dropped because a fixed-width token needs none
+ *  to be read back. */
+export function encodeClaimInviteCompact(invite) {
+    return Buffer.from(claimInviteBytes(invite))
+        .toString("base64")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+/** The bytes behind a token, whichever alphabet it arrived in.
+ *
+ *  Told apart by shape, not by a flag: hex is 384 characters of `[0-9a-f]`
+ *  with an optional `0x`, and anything else is read as base64url. A caller
+ *  who mistypes one gets a length error from the decoder rather than a wrong
+ *  invitation, because both forms are fixed width. */
+function claimInviteTokenBytes(token) {
+    const bare = token.startsWith("0x") || token.startsWith("0X")
+        ? token.slice(2)
+        : token;
+    if (/^[0-9a-fA-F]+$/.test(bare) && bare.length % 2 === 0)
+        return fromHex(bare);
+    const padded = bare.replace(/-/g, "+").replace(/_/g, "/");
+    return new Uint8Array(Buffer.from(padded, "base64"));
 }
+/** Read either encoding. A link minted before the compact form still works,
+ *  and a reader never has to be told which one it is holding. */
 export function decodeClaimInvite(token) {
-    const bytes = fromHex(token.trim());
+    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);