@xgamesfun/solana 0.0.0-stage → 0.24.0

package/js/play/keys.js

@@ -0,0 +1,167 @@
+// The throwaway keys js/play settles with (the key job rule, AGENTS.md), made so a page that closes in the middle of a
+// job can find them again and finish it, or send their SOL back.
+//
+// A key is named by the account its job is about (an order, a hold). With a wallet that signs messages, every key comes
+// from one signature of the wallet's over a fixed text naming the project and the wallet, asked once a session: the
+// key's seed is sha256("loot settle key" | that signature | the name). Ed25519 signatures are deterministic, so after a
+// reload the same signature gives the same keys. A wallet that signs no messages, or whose signature of the text
+// changes from one session to the next (some MPC wallets), gets a random key instead, kept in the page's storage
+// encrypted with a device key the page can use but never read out (WebCrypto, IndexedDB); with no such storage, in
+// memory only, as before.
+import { addressBytes, encodeBase58 } from '../chain/base58.js';
+import { concat, fromBase64, randomBytes, toBase64, toHex, utf8 } from '../chain/bytes.js';
+import { sha256 } from '../chain/sha256.js';
+
+/** The PKCS #8 header of a raw 32-byte Ed25519 seed (RFC 8410). */
+const PKCS8_ED25519 = Uint8Array.from([0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20]);
+
+const DERIVED = 'derived';
+const fromBase64Url = (text) => fromBase64(text.replace(/-/g, '+').replace(/_/g, '/').padEnd(Math.ceil(text.length / 4) * 4, '='));
+
+/** An Ed25519 key from its 32-byte seed: { address, sign(message) }. */
+export async function keyFromSeed(seed, name = null) {
+  const subtle = globalThis.crypto.subtle;
+  const pkcs8 = concat(PKCS8_ED25519, seed);
+  const jwk = await subtle.exportKey('jwk', await subtle.importKey('pkcs8', pkcs8, { name: 'Ed25519' }, true, ['sign']));
+  const signer = await subtle.importKey('pkcs8', pkcs8, { name: 'Ed25519' }, false, ['sign']);
+  return { address: encodeBase58(fromBase64Url(jwk.x)), name, sign: async (message) => new Uint8Array(await subtle.sign('Ed25519', signer, message)) };
+}
+
+/** The text a wallet signs once a session for its settle keys. It moves nothing and says so. */
+export const settleKeysText = (project, wallet) =>
+  `loot: the keys that settle your orders\nproject ${project}\nwallet ${wallet}\n\nSigning this moves nothing. A page that closes before it settles makes the same key again from it, to finish or send your SOL back.`;
+
+/**
+ * The page's storage of keys that can't be made again (`localStorage`), and a device key that encrypts them, kept in
+ * IndexedDB as a non-extractable AES-GCM key. Null where either is missing (then keys live in memory only).
+ */
+export function browserStore() {
+  const ls = globalThis.localStorage;
+  if (!ls || !globalThis.indexedDB) return null;
+  let device = null;
+  return {
+    get: (k) => ls.getItem(k),
+    set: (k, v) => ls.setItem(k, v),
+    remove: (k) => ls.removeItem(k),
+    keys: () => Array.from({ length: ls.length }, (_, i) => ls.key(i)).filter(Boolean),
+    cryptoKey: () => (device ??= deviceKey().catch(() => null)),
+  };
+}
+
+async function deviceKey() {
+  const db = await new Promise((resolve, reject) => {
+    const r = globalThis.indexedDB.open('loot-keys', 1);
+    r.onupgradeneeded = () => r.result.createObjectStore('keys');
+    r.onsuccess = () => resolve(r.result);
+    r.onerror = () => reject(r.error);
+  });
+  const found = await new Promise((resolve, reject) => {
+    const r = db.transaction('keys').objectStore('keys').get('device');
+    r.onsuccess = () => resolve(r.result ?? null);
+    r.onerror = () => reject(r.error);
+  });
+  if (found) return found;
+  const key = await globalThis.crypto.subtle.generateKey({ name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
+  await new Promise((resolve, reject) => {
+    const tx = db.transaction('keys', 'readwrite');
+    tx.objectStore('keys').put(key, 'device');
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+  });
+  return key;
+}
+
+/**
+ * The keys of `wallet` ({ address, signMessage? }) in `project`. `store`: `browserStore()`'s shape ({ get, set, remove,
+ * keys, cryptoKey }), or null. `key(name)` makes the key named by an address (asking the wallet for its signature the
+ * first time in a session); `again(name)` makes it again for a job left unfinished, or finds it stored, or null;
+ * `stored()` lists the names of keys stored; `forget(name)` drops a stored key once its job is done and it is empty.
+ * `how()` says how keys are made: 'derived', 'stored' or 'memory'.
+ */
+export function keyring({ wallet, project, store = null }) {
+  let root = null;
+  const prefix = () => `loot-key:${project}:${wallet.address}:`;
+  const checkName = () => `loot-key-check:${project}:${wallet.address}`;
+  const safe = (f, fallback = null) => {
+    try {
+      return f();
+    } catch {
+      return fallback;
+    }
+  };
+
+  /** The wallet's signature of `settleKeysText`, once a session; null when it signs no messages, refuses, or signs the
+   * text differently from an earlier session (then nothing it signed could be made again). */
+  function signature() {
+    if (!wallet?.signMessage) return Promise.resolve(null);
+    root ??= (async () => {
+      const sig = new Uint8Array(await wallet.signMessage(utf8(settleKeysText(project, wallet.address))));
+      if (sig.length !== 64) return null;
+      const mark = toHex(sha256(sha256(sig))).slice(0, 32);
+      const had = store ? safe(() => store.get(checkName())) : null;
+      if (had && had !== mark) return null;
+      if (!had && store) safe(() => store.set(checkName(), mark));
+      return sig;
+    })().catch(() => null);
+    return root;
+  }
+
+  const derived = (sig, name) => keyFromSeed(sha256(concat(utf8('loot settle key'), sig, addressBytes(name))), name);
+
+  async function seal(seed) {
+    const device = await store?.cryptoKey?.();
+    if (!device) return null;
+    const iv = randomBytes(12);
+    const sealed = new Uint8Array(await globalThis.crypto.subtle.encrypt({ name: 'AES-GCM', iv }, device, seed));
+    return toBase64(concat(iv, sealed));
+  }
+
+  async function open(text) {
+    const device = await store?.cryptoKey?.();
+    if (!device || !text) return null;
+    const bytes = fromBase64(text);
+    return new Uint8Array(await globalThis.crypto.subtle.decrypt({ name: 'AES-GCM', iv: bytes.subarray(0, 12) }, device, bytes.subarray(12)));
+  }
+
+  return {
+    async how() {
+      if (await signature()) return 'derived';
+      return store && (await store.cryptoKey?.()) ? 'stored' : 'memory';
+    },
+
+    /** The key named `name` (an address) for a new job. */
+    async key(name) {
+      const sig = await signature();
+      if (sig) {
+        // Its name is kept, so `recover` finds it once its job's account is gone.
+        if (store) safe(() => store.set(prefix() + name, DERIVED));
+        return derived(sig, name);
+      }
+      const seed = randomBytes(32);
+      const sealed = store ? await seal(seed).catch(() => null) : null;
+      if (sealed) safe(() => store.set(prefix() + name, sealed));
+      return keyFromSeed(seed, name);
+    },
+
+    /** The key named `name` again, for a job left unfinished: made again from the wallet's signature, or read from
+     * storage; null when neither can. `ask`: false to make it only from a signature already given this session. */
+    async again(name, { ask = true } = {}) {
+      const sig = ask || root ? await signature() : null;
+      if (sig) return derived(sig, name);
+      const text = store ? safe(() => store.get(prefix() + name)) : null;
+      const seed = text && text !== DERIVED ? await open(text).catch(() => null) : null;
+      return seed ? keyFromSeed(seed, name) : null;
+    },
+
+    /** The names of the keys this page stored for the wallet (none when keys are made from its signature). */
+    stored() {
+      if (!store) return [];
+      const p = prefix();
+      return safe(() => store.keys(), []).filter((k) => k.startsWith(p)).map((k) => k.slice(p.length));
+    },
+
+    forget(name) {
+      if (store && name) safe(() => store.remove(prefix() + name));
+    },
+  };
+}

package/js/results/index.js

@@ -0,0 +1,184 @@
+// `@xgamesfun/solana/results`: what a game uses with a results server, in a host server or in a player's game page.
+// Browser-safe: Web Crypto only. `server` is RESULTS_SERVER (the public one, on the games.fun play host), or another
+// one's URL. The server confirms who won (from signatures rooted on the chain) and signs grant vouchers; winners claim
+// them with js/play (`claimWins`, `claimGrant`). The program pays a wallet each round once, ever, whatever is signed.
+//
+// A host server (the project's own):
+//   const key = await newKey()                     // once; keep key.secret in the server's secret store
+//   hostCertText({ game, host: key.address, until })   → the owner signs it in their wallet, once
+//   await report({ server, cert, signer: key, game, round: newRound(), endedAt, winners: [{ wallet, place, grant }] })
+//
+// A host server that pays its winners itself, with no server of ours in the way (the owner names the host key among
+// the grant's voucher keys; the program checks every voucher):
+//   const voucher = await signVoucher({ signer: key, game, grant: 1, incarnation, wallet, round, now: clusterNow })
+//   the winner's page: app.claimGrant('prize', { voucher })
+//
+// A giveaway host (a player the owner appointed, signed in with the play host; their page):
+//   const session = await newKey()
+//   await giveaways.open({ server, game, cert: appointment, token, giveaway: newRound(), winners: 3, endsBy, session })
+//   … the game is played …
+//   await giveaways.report({ server, game, giveaway, session, endedAt, winners: [{ wallet, place }], grant })
+import { decodeBase58, encodeBase58 } from '../chain/base58.js';
+import { toHex } from '../chain/bytes.js';
+import { pda, voucherBytes } from '../client/index.js';
+import { canonicalJson, drawText, entryText, lockText, resultBytes, rosterHash } from './wire.js';
+
+export { canonicalJson, CERT_KINDS, CLUSTERS, drawText, entryText, giveawayHostText, hostCertText, lockText, NO_GRANT, RESULT_DOMAIN, resultBytes, revokeGiveawayText, revokeText, rosterHash } from './wire.js';
+
+/** games.fun's results server, on its play host (devnet until the program's audit). */
+export const RESULTS_SERVER = 'https://play.xgames.fun/xsolana';
+
+const subtle = () => globalThis.crypto.subtle;
+/** A value as a query's value: encoded, so a `&`, `#` or `/` in it is part of the value. */
+const q = (value) => encodeURIComponent(String(value));
+/**
+ * A value as one segment of a URL's path: encoded, so a `/` or `?` in it stays inside the segment. One that is empty,
+ * `.` or `..` (which a URL reads as a step up the path, encoded or not) is refused.
+ */
+const seg = (value) => {
+  const text = String(value);
+  if (text === '' || text === '.' || text === '..') throw new RangeError(`${JSON.stringify(text)} can't be a part of a path.`);
+  return encodeURIComponent(text);
+};
+
+/** A fresh round id: 16 random bytes, in hex. Make it when the round starts. */
+export const newRound = () => toHex(globalThis.crypto.getRandomValues(new Uint8Array(16)));
+
+/**
+ * A fresh Ed25519 key: { address, sign(bytes) → Promise<64 bytes>, secret }. `secret` is its 32-byte seed in base58,
+ * for a host server to keep in its secret store; a page's session key never needs it.
+ */
+export async function newKey() {
+  const pair = await subtle().generateKey({ name: 'Ed25519' }, true, ['sign', 'verify']);
+  const jwk = await subtle().exportKey('jwk', pair.privateKey);
+  return keyOf(pair.privateKey, base64url(jwk.x), jwk.d);
+}
+
+/** The key a host server kept (`secret`: its seed in base58). */
+export async function keyFromSecret(secret) {
+  const seed = decodeBase58(secret);
+  if (seed.length !== 32) throw new Error('A host key secret is 32 bytes in base58.');
+  const pkcs8 = new Uint8Array([0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20, ...seed]);
+  const privateKey = await subtle().importKey('pkcs8', pkcs8, { name: 'Ed25519' }, true, ['sign']);
+  const jwk = await subtle().exportKey('jwk', privateKey);
+  return keyOf(privateKey, base64url(jwk.x), jwk.d);
+}
+
+function keyOf(privateKey, publicBytes, d) {
+  return {
+    address: encodeBase58(publicBytes),
+    secret: encodeBase58(base64url(d)),
+    sign: async (message) => new Uint8Array(await subtle().sign({ name: 'Ed25519' }, privateKey, message)),
+  };
+}
+
+function base64url(text) {
+  const bin = atob(text.replace(/-/g, '+').replace(/_/g, '/'));
+  return Uint8Array.from(bin, (c) => c.charCodeAt(0));
+}
+
+/** One signer's signature of a result: { key, signature }. `signer` is a key from newKey, or anything with sign(). */
+export async function signResult(signer, result, cluster = 'devnet') {
+  return { key: signer.address, signature: encodeBase58(await signer.sign(resultBytes({ ...result, cluster }))) };
+}
+
+/**
+ * A host server reports a round. `cert`: the owner's { text, signature } certifying `signer`, the host key. Retrying
+ * with the same result is safe: it is the same answer. Returns the server's answer, { result, vouchers }, or throws its
+ * { code, why }.
+ */
+export async function report({ server, cert, signer, game, round, endedAt, winners, cluster = 'devnet', fetchImpl = globalThis.fetch }) {
+  const result = { game, round, endedAt, winners };
+  const all = [await signResult(signer, result, cluster)];
+  const response = await fetchImpl(`${server.replace(/\/$/, '')}/v1/results`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ ...result, cert, signatures: all }),
+  });
+  return answerOf(response);
+}
+
+/**
+ * A server's answer: its JSON body when the status is a success. Otherwise it throws the server's own { code, why }
+ * when the body says them, or the status in words (an HTML error page from a proxy, an empty body).
+ */
+async function answerOf(response) {
+  const answer = await response.json().catch(() => null);
+  if (!response.ok) throw Object.assign(new Error(answer?.error?.why ?? `The results server answered ${response.status}${response.statusText ? ` ${response.statusText}` : ''}.`), { code: answer?.error?.code, status: response.status });
+  if (answer === null || typeof answer !== 'object') throw Object.assign(new Error(`The results server answered ${response.status} with no JSON.`), { status: response.status });
+  return answer;
+}
+
+/** A wallet's vouchers for a round it won: [{ grant, publicKey, signature, round, expires, … }]. */
+export async function fetchVouchers({ server, game, round, wallet, fetchImpl = globalThis.fetch }) {
+  const response = await fetchImpl(`${server.replace(/\/$/, '')}/v1/vouchers?game=${q(game)}&round=${q(round)}&wallet=${q(wallet)}`);
+  return (await answerOf(response)).vouchers;
+}
+
+/**
+ * A loot grant voucher the host key signs itself, for a host server whose key the grant names (no results server
+ * involved): the program checks it and pays only `wallet`, within the grant's limits. `round` is the result's round id
+ * (16 bytes hex): the program pays a wallet each round once, ever, so the voucher may be signed again, any time, and
+ * still pays once. `incarnation` is the grant's (`Grant.incarnation`): a voucher pays only the grant it was signed
+ * for, never one written again at the same address. `now` is the cluster's clock (unix s); the voucher lives
+ * `seconds` from it, 30 days at most. `amount`: the tokens this claim gives, in base units, for a grant of a fixed amount
+ * of tokens (a rank's reward), at most the grant's; 0 (the default) gives the grant's prize as it is.
+ * Returns { wallet, grant, incarnation, publicKey, signature, round, expires, personHash, amount } for js/play claimGrant,
+ * plain JSON (`incarnation` and `amount` as decimal text), so a server can send it as it is.
+ */
+export async function signVoucher({ signer, game, grant, incarnation, wallet, round, now, seconds = 7 * 86_400, personHash = null, amount = 0n }) {
+  if (!(Number(seconds) > 0)) throw new RangeError('A voucher lives some seconds from now (`seconds` above 0): one that has run out already pays nothing.');
+  if (Number(seconds) > 30 * 86_400) throw new Error('A voucher lives 30 days at most.');
+  // The cluster's clock comes as a number or a bigint (an RPC's, a decoded Clock's); `expires` is a number either way.
+  const expires = Math.floor(typeof now === 'bigint' ? Number(now) : now) + Number(seconds);
+  if (!Number.isSafeInteger(expires)) throw new RangeError('A voucher needs the cluster\'s clock (`now`, unix seconds).');
+  const message = voucherBytes({ grant: pda.grant(game, grant), incarnation, wallet, personHash, round, expires, amount: BigInt(amount) });
+  return { wallet, grant, incarnation: String(BigInt(incarnation)), publicKey: signer.address, signature: encodeBase58(await signer.sign(message)), round, expires, personHash: personHash ?? '0'.repeat(64), amount: String(BigInt(amount)) };
+}
+
+/** Posts JSON to the server and answers its body, or throws its { code, why }. */
+async function post(server, path, body, fetchImpl) {
+  const response = await fetchImpl(`${server.replace(/\/$/, '')}${path}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
+  return answerOf(response);
+}
+
+/** Gets JSON from the server and answers its body, or throws its { code, why }. */
+const fetchJson = async (server, path, fetchImpl) => answerOf(await fetchImpl(`${server.replace(/\/$/, '')}${path}`));
+
+/**
+ * A draw, from the organizer's side and the players'. `signMessage(text) → signature bytes` is the organizer's wallet
+ * (its signMessage) or a host key's sign; `by` its address; `cert` the owner's host certificate when `by` is a host key.
+ */
+export const draws = {
+  open: async ({ server, signMessage, by, cert = null, rates = null, fetchImpl = globalThis.fetch, ...spec }) => {
+    const ratesHash = rates ? Array.from(new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(canonicalJson(rates)))), (b) => b.toString(16).padStart(2, '0')).join('') : 'default';
+    const text = drawText({ ...spec, rates: ratesHash });
+    return post(server, '/v1/draws', { text, signature: encodeBase58(await signMessage(new TextEncoder().encode(text))), by, ...(cert ? { cert } : {}), ...(rates ? { rates } : {}) }, fetchImpl);
+  },
+  /** A player enters with their play-host token, or with their wallet's signature (`wallet`, `signMessage`). */
+  enter: async ({ server, game, draw, token = null, wallet = null, signMessage = null, cluster = 'devnet', fetchImpl = globalThis.fetch }) => {
+    if (token) return post(server, `/v1/draws/${seg(game)}/${seg(draw)}/entries`, { token }, fetchImpl);
+    const text = entryText({ cluster, game, draw });
+    return post(server, `/v1/draws/${seg(game)}/${seg(draw)}/entries`, { wallet, text, signature: encodeBase58(await signMessage(new TextEncoder().encode(text))) }, fetchImpl);
+  },
+  /** Locks the players the server holds now to `beacon`, a drand round still to come. Checks their hash itself. */
+  lock: async ({ server, game, draw, beacon, signMessage, by, cert = null, cluster = 'devnet', net = 'quicknet', fetchImpl = globalThis.fetch }) => {
+    const { draw: view } = await fetchJson(server, `/v1/draws/${seg(game)}/${seg(draw)}`, fetchImpl);
+    const text = lockText({ cluster, game, draw, roster: await rosterHash(view.entries), players: view.entries.length, beacon, net });
+    return post(server, `/v1/draws/${seg(game)}/${seg(draw)}/lock`, { text, signature: encodeBase58(await signMessage(new TextEncoder().encode(text))), by, ...(cert ? { cert } : {}) }, fetchImpl);
+  },
+  /** The draw as anyone may check it; settled, with its result, once its beacon round is out. */
+  get: async ({ server, game, draw, fetchImpl = globalThis.fetch }) => (await fetchJson(server, `/v1/draws/${seg(game)}/${seg(draw)}`, fetchImpl)).draw,
+};
+
+/** A giveaway, from its appointed host's page. */
+export const giveaways = {
+  /** Opens one: `cert` the owner's appointment, `token` the host's play-host sign-in, `session` a key from newKey(). */
+  open: async ({ server, game, cert, token, giveaway, winners, endsBy, session, fetchImpl = globalThis.fetch }) => post(server, `/v1/giveaways/${seg(game)}`, { cert, token, giveaway, winners, endsBy, session: session.address }, fetchImpl),
+  /** Reports its result, signed by its session key. `grant`: the host's grant (each winner is paid from it). */
+  report: async ({ server, game, giveaway, session, endedAt, winners, grant, cluster = 'devnet', fetchImpl = globalThis.fetch }) => {
+    const signed = winners.map((w) => ({ wallet: w.wallet, place: w.place, grant }));
+    const signature = encodeBase58(await session.sign(resultBytes({ cluster, game, round: giveaway, endedAt, winners: signed })));
+    return post(server, `/v1/giveaways/${seg(game)}/${seg(giveaway)}/result`, { endedAt, winners: winners.map(({ wallet, place }) => ({ wallet, place })), signature }, fetchImpl);
+  },
+};

package/js/results/wire.js

@@ -0,0 +1,90 @@
+// The exact bytes and texts a results server checks (the public one runs at https://play.xgames.fun/xsolana), shared
+// with whoever signs them: a host server, a player's game page, an owner's wallet. Browser-safe: no Node imports.
+import { addressBytes } from '../chain/base58.js';
+import { concat, fromHex, uintLE, utf8 } from '../chain/bytes.js';
+
+export const RESULT_DOMAIN = 'loot-result-v1';
+export const NO_GRANT = 0xffff;
+export const CLUSTERS = Object.freeze({ devnet: 0, mainnet: 1 });
+
+/** Each certificate's first line, and the lines that follow it, in order. */
+export const CERT_KINDS = Object.freeze({
+  host: { title: 'loot host key', fields: ['cluster', 'game', 'host', 'until'] },
+  revoke: { title: 'loot revoke host key', fields: ['cluster', 'game', 'host'] },
+  draw: { title: 'loot draw', fields: ['cluster', 'game', 'draw', 'engine', 'winners', 'prizes', 'payout', 'identity', 'slug', 'rates'] },
+  lock: { title: 'loot draw lock', fields: ['cluster', 'game', 'draw', 'roster', 'players', 'beacon'] },
+  entry: { title: 'loot entry', fields: ['cluster', 'game', 'draw'] },
+  giveaway: { title: 'loot giveaway host', fields: ['cluster', 'game', 'who', 'slug', 'grant', 'until'] },
+  revokeGiveaway: { title: 'loot revoke giveaway host', fields: ['cluster', 'game', 'who'] },
+});
+
+/** One field's value, on its own line: a value with a line break in it (which would read as another field) is refused. */
+const field = (name, value) => {
+  if (/[\r\n]/.test(String(value))) throw new RangeError(`A certificate's ${name} is one line: ${JSON.stringify(String(value))} has a line break.`);
+  return value;
+};
+const write = (kind, values) => [CERT_KINDS[kind].title, ...CERT_KINDS[kind].fields.map((f) => `${f}: ${field(f, values[f])}`)].join('\n');
+
+/** The text the owner signs to let `host` report `game`'s results until `until` (unix seconds). */
+export const hostCertText = ({ cluster = 'devnet', game, host, until }) => write('host', { cluster, game, host, until });
+/** The text the owner signs to take `host` back. */
+export const revokeText = ({ cluster = 'devnet', game, host }) => write('revoke', { cluster, game, host });
+
+/**
+ * The text the organizer (the game's owner or authority, or a host key they certified) signs to open a draw: a round
+ * whose winners an engine computes from the locked players and a future beacon value. `prizes`: [{ place, grant }];
+ * `payout`: 'vouchers' (the server vouches for each winner) or 'list' (the owner writes the winners' list on the grant);
+ * `identity`: 'linked' (a play-host sign-in linked to X, one entry a person) or 'wallet' (a wallet's own signature);
+ * `slug`: the game's play-host name (its tokens' audience), or '-'; `rates`: the sha256 of the engine's rates (canonical
+ * JSON), or 'default'.
+ */
+export const drawText = ({ cluster = 'devnet', game, draw, engine, winners, prizes = [], payout = 'vouchers', identity = 'linked', slug = '-', rates = 'default' }) =>
+  write('draw', { cluster, game, draw, engine, winners, prizes: prizes.length ? prizes.map((p) => `${p.place}:${p.grant}`).join(' ') : 'none', payout, identity, slug, rates });
+/** The text the organizer signs to lock a draw's players (`roster`: rosterHash) to a beacon round still to come. */
+export const lockText = ({ cluster = 'devnet', game, draw, roster, players, beacon, net = 'quicknet' }) => write('lock', { cluster, game, draw, roster, players, beacon: `${net} ${beacon}` });
+/** The text a player's wallet signs to enter a draw (identity 'wallet'). */
+export const entryText = ({ cluster = 'devnet', game, draw }) => write('entry', { cluster, game, draw });
+
+/**
+ * The text the owner (or authority) signs to appoint a giveaway host: `who` is "x:<X account id>" (the host signs in
+ * with that X account through the play host) or a wallet address; their giveaways pay from grant `grant` alone.
+ */
+export const giveawayHostText = ({ cluster = 'devnet', game, who, slug, grant, until }) => write('giveaway', { cluster, game, who, slug, grant, until });
+/** The text the owner (or authority) signs to take a giveaway host back. */
+export const revokeGiveawayText = ({ cluster = 'devnet', game, who }) => write('revokeGiveaway', { cluster, game, who });
+
+/** A draw's players, as one hash: each `id<TAB>wallet`, sorted by id, one a line; sha256, hex. */
+export async function rosterHash(entries) {
+  const text = [...entries].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)).map((e) => `${e.id}\t${e.wallet}`).join('\n');
+  return Array.from(new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', utf8(text))), (b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+/** JSON with every object's keys sorted: one text for one value, so its hash means one thing. */
+export function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (value && typeof value === 'object') return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(',')}}`;
+  return JSON.stringify(value);
+}
+
+/**
+ * The bytes a result's signers sign:
+ *   "loot-result-v1" | cluster (1) | game (32) | round (16) | endedAt (u64 LE)
+ *   | winners (u8 count; each wallet (32) | place (u8) | grant id (u16 LE, 0xffff: none))
+ * Every field has one length, so one set of bytes means one result: an unknown cluster, a round that is not 16 bytes, a
+ * place past 255 and more than 255 winners are refused, never written as something else.
+ */
+export function resultBytes({ cluster = 'devnet', game, round, endedAt, winners }) {
+  if (!Object.hasOwn(CLUSTERS, cluster)) throw new RangeError(`Unknown cluster ${JSON.stringify(cluster)}: a result names ${Object.keys(CLUSTERS).join(' or ')}.`);
+  const roundAt = typeof round === 'string' && /^[0-9a-f]{32}$/i.test(round) ? fromHex(round) : round instanceof Uint8Array && round.length === 16 ? round : null;
+  if (!roundAt) throw new RangeError('A result\'s round is 16 bytes (32 hex characters).');
+  if (!Array.isArray(winners) || winners.length > 255) throw new RangeError('A result names at most 255 winners.');
+  return concat(
+    utf8(RESULT_DOMAIN),
+    Uint8Array.of(CLUSTERS[cluster]),
+    addressBytes(game),
+    roundAt,
+    uintLE(BigInt(endedAt), 8),
+    Uint8Array.of(winners.length),
+    ...winners.map((w) => concat(addressBytes(w.wallet), uintLE(w.place, 1), uintLE(w.grant ?? NO_GRANT, 2))),
+  );
+}

package/package.json

@@ -1,6 +1,102 @@
 {
   "name": "@xgamesfun/solana",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.24.0",
+  "mcpName": "io.github.XGamesFun/solana-kit",
+  "description": "One shared Solana program for game and community economies, its JS client, and the tools that let an AI agent design, check, simulate and launch an economy on it.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/XGamesFun/solana-kit.git"
+  },
+  "homepage": "https://github.com/XGamesFun/solana-kit#readme",
+  "bugs": {
+    "url": "https://github.com/XGamesFun/solana-kit/issues"
+  },
+  "keywords": [
+    "solana",
+    "economy",
+    "loot-box",
+    "staking",
+    "nft",
+    "game",
+    "mcp",
+    "agent"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./js/index.js"
+    },
+    "./client": {
+      "types": "./types/client/index.d.ts",
+      "default": "./js/client/index.js"
+    },
+    "./chain/*": {
+      "types": "./types/chain/*.d.ts",
+      "default": "./js/chain/*.js"
+    },
+    "./play": {
+      "types": "./types/play/index.d.ts",
+      "default": "./js/play/index.js"
+    },
+    "./results": {
+      "types": "./types/results/index.d.ts",
+      "default": "./js/results/index.js"
+    },
+    "./idl.json": "./js/client/idl/loot.json",
+    "./package.json": "./package.json",
+    "./release.json": "./release.json"
+  },
+  "sideEffects": [
+    "./bin/xsolana.mjs",
+    "./js/approve/page.js"
+  ],
+  "files": [
+    "js/",
+    "!js/test/",
+    "!js/sim/",
+    "types/",
+    "release.json",
+    "bin/",
+    "skills/",
+    "examples/*.json",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "DISCLAIMER.md"
+  ],
+  "scripts": {
+    "test": "node --test \"js/test/**/*.test.mjs\"",
+    "lint": "eslint .",
+    "types": "tsc -p tsconfig.types.json",
+    "fixtures": "node scripts/fetch-fixtures.mjs",
+    "check": "node scripts/fetch-fixtures.mjs --check && node scripts/sync-skills.mjs --check && node scripts/release-manifest.mjs --check && eslint . && npm test",
+    "check:idl": "node scripts/sync-idl.mjs --check",
+    "sync-idl": "node scripts/sync-idl.mjs",
+    "sync-skills": "node scripts/sync-skills.mjs",
+    "release:manifest": "node scripts/release-manifest.mjs",
+    "prepack": "node scripts/release-manifest.mjs --check && tsc -p tsconfig.types.json"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "ajv": "8.20.0",
+    "eslint": "10.13.0",
+    "globals": "17.13.0",
+    "litesvm": "1.6.1",
+    "playwright-core": "1.64.1",
+    "typescript": "7.0.2"
+  },
+  "bin": {
+    "xsolana": "bin/xsolana.mjs"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "types": "./types/index.d.ts"
+}

package/release.json

@@ -0,0 +1,8 @@
+{
+  "version": "0.24.0",
+  "programId": "9cwqM1TXytPnFZsLfmUyv2dg4uW6Ch9C6UJVPns7NFQ",
+  "sbfBytes": 1727272,
+  "sbfSha256": "1bf01fbceb390c8888921df95f711d32e805554401e2c128e83eb16fcb11098c",
+  "idlSha256": "32dc0d5ed56fa7fb2ef8e90ef8d96d1d8bbe940b624d3d5b636933af20ae56b4",
+  "clientSha256": "f2a0f00386a08ecbd1fd939d53889d1a7a151997bf16684c641dd98a838b8d72"
+}