@xgamesfun/solana 0.0.0-stage → 0.24.0

package/types/play/keys.d.ts

@@ -0,0 +1,51 @@
+/** An Ed25519 key from its 32-byte seed: { address, sign(message) }. */
+export declare function keyFromSeed(seed: any, name?: null): Promise<{
+    address: string;
+    name: null;
+    sign: (message: any) => Promise<Uint8Array<ArrayBuffer>>;
+}>;
+/** The text a wallet signs once a session for its settle keys. It moves nothing and says so. */
+export declare const settleKeysText: (project: any, wallet: any) => string;
+/**
+ * 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 declare function browserStore(): {
+    get: (k: any) => string | null;
+    set: (k: any, v: any) => void;
+    remove: (k: any) => void;
+    keys: () => (string | null)[];
+    cryptoKey: () => any;
+} | null;
+/**
+ * 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 declare function keyring({ wallet, project, store }: {
+    project: any;
+    store?: null | undefined;
+    wallet: any;
+}): {
+    how(): Promise<"derived" | "memory" | "stored">;
+    /** The key named `name` (an address) for a new job. */
+    key(name: any): Promise<{
+        address: string;
+        name: null;
+        sign: (message: any) => Promise<Uint8Array<ArrayBuffer>>;
+    }>;
+    /** 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. */
+    again(name: any, { ask }?: {
+        ask?: boolean | undefined;
+    }): Promise<{
+        address: string;
+        name: null;
+        sign: (message: any) => Promise<Uint8Array<ArrayBuffer>>;
+    } | null>;
+    /** The names of the keys this page stored for the wallet (none when keys are made from its signature). */
+    stored(): any;
+    forget(name: any): void;
+};

package/types/results/index.d.ts

@@ -0,0 +1,155 @@
+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 declare const RESULTS_SERVER = "https://play.xgames.fun/xsolana";
+/** A fresh round id: 16 random bytes, in hex. Make it when the round starts. */
+export declare const newRound: () => string;
+/**
+ * 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 declare function newKey(): Promise<{
+    address: string;
+    secret: string;
+    sign: (message: any) => Promise<Uint8Array<ArrayBuffer>>;
+}>;
+/** The key a host server kept (`secret`: its seed in base58). */
+export declare function keyFromSecret(secret: any): Promise<{
+    address: string;
+    secret: string;
+    sign: (message: any) => Promise<Uint8Array<ArrayBuffer>>;
+}>;
+/** One signer's signature of a result: { key, signature }. `signer` is a key from newKey, or anything with sign(). */
+export declare function signResult(signer: any, result: any, cluster?: string): Promise<{
+    key: any;
+    signature: string;
+}>;
+/**
+ * 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 declare function report({ server, cert, signer, game, round, endedAt, winners, cluster, fetchImpl }: {
+    cert: any;
+    cluster?: string | undefined;
+    endedAt: any;
+    fetchImpl?: typeof fetch | undefined;
+    game: any;
+    round: any;
+    server: any;
+    signer: any;
+    winners: any;
+}): Promise<any>;
+/** A wallet's vouchers for a round it won: [{ grant, publicKey, signature, round, expires, … }]. */
+export declare function fetchVouchers({ server, game, round, wallet, fetchImpl }: {
+    fetchImpl?: typeof fetch | undefined;
+    game: any;
+    round: any;
+    server: any;
+    wallet: any;
+}): Promise<any>;
+/**
+ * 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 declare function signVoucher({ signer, game, grant, incarnation, wallet, round, now, seconds, personHash, amount }: {
+    amount?: bigint | undefined;
+    game: any;
+    grant: any;
+    incarnation: any;
+    now: any;
+    personHash?: null | undefined;
+    round: any;
+    seconds?: number | undefined;
+    signer: any;
+    wallet: any;
+}): Promise<{
+    wallet: any;
+    grant: any;
+    incarnation: string;
+    publicKey: any;
+    signature: string;
+    round: any;
+    expires: number;
+    personHash: string;
+    amount: string;
+}>;
+/**
+ * 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 declare const draws: {
+    open: ({ server, signMessage, by, cert, rates, fetchImpl, ...spec }: {
+        [x: string]: any;
+        by: any;
+        cert?: null | undefined;
+        fetchImpl?: typeof fetch | undefined;
+        rates?: null | undefined;
+        server: any;
+        signMessage: any;
+    }) => Promise<any>;
+    /** A player enters with their play-host token, or with their wallet's signature (`wallet`, `signMessage`). */
+    enter: ({ server, game, draw, token, wallet, signMessage, cluster, fetchImpl }: {
+        cluster?: string | undefined;
+        draw: any;
+        fetchImpl?: typeof fetch | undefined;
+        game: any;
+        server: any;
+        signMessage?: null | undefined;
+        token?: null | undefined;
+        wallet?: null | undefined;
+    }) => Promise<any>;
+    /** Locks the players the server holds now to `beacon`, a drand round still to come. Checks their hash itself. */
+    lock: ({ server, game, draw, beacon, signMessage, by, cert, cluster, net, fetchImpl }: {
+        beacon: any;
+        by: any;
+        cert?: null | undefined;
+        cluster?: string | undefined;
+        draw: any;
+        fetchImpl?: typeof fetch | undefined;
+        game: any;
+        net?: string | undefined;
+        server: any;
+        signMessage: any;
+    }) => Promise<any>;
+    /** The draw as anyone may check it; settled, with its result, once its beacon round is out. */
+    get: ({ server, game, draw, fetchImpl }: {
+        draw: any;
+        fetchImpl?: typeof fetch | undefined;
+        game: any;
+        server: any;
+    }) => Promise<any>;
+};
+/** A giveaway, from its appointed host's page. */
+export declare const giveaways: {
+    /** Opens one: `cert` the owner's appointment, `token` the host's play-host sign-in, `session` a key from newKey(). */
+    open: ({ server, game, cert, token, giveaway, winners, endsBy, session, fetchImpl }: {
+        cert: any;
+        endsBy: any;
+        fetchImpl?: typeof fetch | undefined;
+        game: any;
+        giveaway: any;
+        server: any;
+        session: any;
+        token: any;
+        winners: any;
+    }) => Promise<any>;
+    /** Reports its result, signed by its session key. `grant`: the host's grant (each winner is paid from it). */
+    report: ({ server, game, giveaway, session, endedAt, winners, grant, cluster, fetchImpl }: {
+        cluster?: string | undefined;
+        endedAt: any;
+        fetchImpl?: typeof fetch | undefined;
+        game: any;
+        giveaway: any;
+        grant: any;
+        server: any;
+        session: any;
+        winners: any;
+    }) => Promise<any>;
+};

package/types/results/wire.d.ts

@@ -0,0 +1,122 @@
+export declare const RESULT_DOMAIN = "loot-result-v1";
+export declare const NO_GRANT = 65535;
+export declare const CLUSTERS: Readonly<{
+    devnet: 0;
+    mainnet: 1;
+}>;
+/** Each certificate's first line, and the lines that follow it, in order. */
+export declare const CERT_KINDS: Readonly<{
+    host: {
+        title: string;
+        fields: string[];
+    };
+    revoke: {
+        title: string;
+        fields: string[];
+    };
+    draw: {
+        title: string;
+        fields: string[];
+    };
+    lock: {
+        title: string;
+        fields: string[];
+    };
+    entry: {
+        title: string;
+        fields: string[];
+    };
+    giveaway: {
+        title: string;
+        fields: string[];
+    };
+    revokeGiveaway: {
+        title: string;
+        fields: string[];
+    };
+}>;
+/** The text the owner signs to let `host` report `game`'s results until `until` (unix seconds). */
+export declare const hostCertText: ({ cluster, game, host, until }: {
+    cluster?: string | undefined;
+    game: any;
+    host: any;
+    until: any;
+}) => string;
+/** The text the owner signs to take `host` back. */
+export declare const revokeText: ({ cluster, game, host }: {
+    cluster?: string | undefined;
+    game: any;
+    host: any;
+}) => string;
+/**
+ * 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 declare const drawText: ({ cluster, game, draw, engine, winners, prizes, payout, identity, slug, rates }: {
+    cluster?: string | undefined;
+    draw: any;
+    engine: any;
+    game: any;
+    identity?: string | undefined;
+    payout?: string | undefined;
+    prizes?: never[] | undefined;
+    rates?: string | undefined;
+    slug?: string | undefined;
+    winners: any;
+}) => string;
+/** The text the organizer signs to lock a draw's players (`roster`: rosterHash) to a beacon round still to come. */
+export declare const lockText: ({ cluster, game, draw, roster, players, beacon, net }: {
+    beacon: any;
+    cluster?: string | undefined;
+    draw: any;
+    game: any;
+    net?: string | undefined;
+    players: any;
+    roster: any;
+}) => string;
+/** The text a player's wallet signs to enter a draw (identity 'wallet'). */
+export declare const entryText: ({ cluster, game, draw }: {
+    cluster?: string | undefined;
+    draw: any;
+    game: any;
+}) => string;
+/**
+ * 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 declare const giveawayHostText: ({ cluster, game, who, slug, grant, until }: {
+    cluster?: string | undefined;
+    game: any;
+    grant: any;
+    slug: any;
+    until: any;
+    who: any;
+}) => string;
+/** The text the owner (or authority) signs to take a giveaway host back. */
+export declare const revokeGiveawayText: ({ cluster, game, who }: {
+    cluster?: string | undefined;
+    game: any;
+    who: any;
+}) => string;
+/** A draw's players, as one hash: each `id<TAB>wallet`, sorted by id, one a line; sha256, hex. */
+export declare function rosterHash(entries: any): Promise<string>;
+/** JSON with every object's keys sorted: one text for one value, so its hash means one thing. */
+export declare function canonicalJson(value: any): any;
+/**
+ * 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 declare function resultBytes({ cluster, game, round, endedAt, winners }: {
+    cluster?: string | undefined;
+    endedAt: any;
+    game: any;
+    round: any;
+    winners: any;
+}): Uint8Array<any>;