@xgamesfun/solana 0.25.4 → 0.26.0

package/types/play/index.d.ts

@@ -346,17 +346,17 @@ export declare function solanaApp({ spec, rpcUrl, rpc, wallet, programs, now, ke
      * signs no messages. Returns [{ name, key, settled } | { name, key, swept } | { name, key, waiting }].
      */
     recover(): Promise<({
+        waiting?: undefined;
         name: null;
         key: string;
         error: any;
-        waiting?: undefined;
         swept?: undefined;
     } | {
+        waiting?: undefined;
         name: null;
         key: string;
         settled: any;
         won: any;
-        waiting?: undefined;
         swept?: undefined;
     } | {
         name: null;
@@ -371,14 +371,16 @@ export declare function solanaApp({ spec, rpcUrl, rpc, wallet, programs, now, ke
     })[]>;
     /** Gives an order's payment back once its time has come (a roll that failed or never came). */
     refund(orderAddress: any): Promise<any>;
-    /** Asks the oracle for a roll a mission, a recipe or a prize made (anyone may; the asker pays the oracle). On a box
-     * with nothing in stock only the order's player may ask, a slot after it was made or last asked, and that ends the
-     * roll there with nothing, no oracle (a lot its winner paid for fails, for its refund). */
-    askRoll: (orderAddress: any) => Promise<any>;
+    /** Asks the oracle for a roll a mission, a recipe or a prize made (its player or the project's keys may; the asker
+     * pays the oracle). Its first ask fixes its odds: the player's profile, and an NFT they show (`shown`; by default
+     * their collectible that raises the box's odds the most), count then. On a box with nothing in stock only the order's
+     * player may ask, a slot after it was made or last asked, and that ends the roll there with nothing, no oracle (a lot
+     * its winner paid for fails, for its refund). */
+    askRoll: (orderAddress: any, options?: {}) => Promise<any>;
     /**
      * Pays a payment of the economy (an entry, an attempt, a tip). `amount`: what the player chose, in whole units, for
      * a payment with `any` (at least its `amount`). `chosenRecipient`: the wallet the player names for a share the
-     * payment lets them choose (a referrer), never their own. `holders`: asset → holder, for a holder's share (read
+     * payment lets them choose (a referrer; their own wallet too, which then pays them back their share). `holders`: asset → holder, for a holder's share (read
      * now when not given).
      */
     pay(paymentKey: any, { amount: chosen, holders, chosenRecipient, ...others }?: Readonly<Record<string, any>>): Promise<any>;
@@ -403,10 +405,29 @@ export declare function solanaApp({ spec, rpcUrl, rpc, wallet, programs, now, ke
         round: any;
         sold: any;
         drawsAt: number | null;
+        salesCloseAt: number | null;
+        timeWeighted: boolean;
+        weight: bigint | null;
+        ticketWeight: bigint | null;
+        ticketShare: number | null;
         nftTicket: boolean;
         incarnation: any;
         revision: any;
     }[]>;
+    /**
+     * What `count` tickets of a lottery bought now would weigh in its current round's draw, before they are bought:
+     * { tickets, weight, total, share, salesCloseAt, timeWeighted }. In a lottery that weighs tickets by time, each
+     * ticket weighs the seconds from its purchase to the close of sales, so the same tickets bought later weigh less;
+     * `share` is the purchase's part of the round's weight with it (0 to 1), its chance at each place as things stand.
+     */
+    ticketWeight(lotteryKey: any, count?: number): Promise<{
+        weight: bigint;
+        total: bigint;
+        share: number;
+        tickets: bigint;
+        salesCloseAt: number;
+        timeWeighted: boolean;
+    }>;
     /**
      * Buys `count` tickets of a lottery, on the terms the player was shown: `listing`, the lottery as `lotteries()`
      * showed it (a lottery changed since, its price or anything else, is refused rather than paid), or `maxPrice`, the
@@ -416,7 +437,7 @@ export declare function solanaApp({ spec, rpcUrl, rpc, wallet, programs, now, ke
      * passes its rule: `nft`, its address (held by the project until the draw, then burned, given on or stashed; back to
      * the player if the round is cancelled). `listProof`: for a list gate.
      */
-    buyTickets(lotteryKey: any, count?: number, { shown, chosenRecipient, listProof, nft: paidWith, listing, maxPrice, ...others }?: Readonly<Record<string, any>>): Promise<any>;
+    buyTickets(lotteryKey: any, count?: number, { shown, chosenRecipient, listProof, nft: paidWith, listing, maxPrice, acceptLeftover, ...others }?: Readonly<Record<string, any>>): Promise<any>;
     /**
      * Writes an NFT's traits from the project's traits tree (`traits` in the spec) into its Sheet, where rules read them:
      * anyone may, paying the Sheet's rent. `attributes` ([{ key, value }]) and `proof` come from the project's tree
@@ -439,14 +460,15 @@ export declare function solanaApp({ spec, rpcUrl, rpc, wallet, programs, now, ke
      * Core asset, a Token Metadata NFT's mint (legacy or pNFT), or a compressed NFT's asset id. In a farm that watches,
      * an NFT whose last staker sold it takes their seat over. A farm with an end takes none at its end or after it.
      */
-    stakeNft(farmKey: any, asset: any, tier?: number, { extra, transfers, ...others }?: Readonly<Record<string, any>>): Promise<any>;
+    stakeNft(farmKey: any, asset: any, tier?: number, { extra, transfers, acceptLeftover, ...others }?: Readonly<Record<string, any>>): Promise<any>;
     /**
      * Releases the collectible after its lock: it grows on its way out (a farm with `growth`), and from its own seat
-     * takes its tier's prize (a mission: `prize.rs`). `forfeit` gives up rewards, and the prize, that cannot move.
-     * Returns the signature, or { signature, roll } when it makes a roll (a mission's result on the NFT, or a chest),
+     * takes its tier's prize (a mission: `prize.rs`). `forfeit` gives up rewards, and the prize, that cannot move. A
+     * prize that can't be given now refuses the leave and the NFT stays (`needPrize`, true by default); `needPrize: false`
+     * leaves without it (the receipt says `prize_missed`). Returns the signature, or { signature, roll } when it makes a roll (a mission's result on the NFT, or a chest),
      * which `collect` then finishes.
      */
-    unstakeNft(farmKey: any, asset: any, { forfeit, extra, transfers, ...others }?: Readonly<Record<string, any>>): Promise<any>;
+    unstakeNft(farmKey: any, asset: any, { forfeit, needPrize, extra, transfers, acceptLeftover, ...others }?: Readonly<Record<string, any>>): Promise<any>;
     /**
      * What farm `farmKey` has to walk: `{ ends, needsWalk, parts }`, the times its seats stop earning it has passed and not
      * yet credited up to, whether a move can no longer do them in its own transaction, and how many transactions
@@ -499,6 +521,7 @@ export declare function solanaApp({ spec, rpcUrl, rpc, wallet, programs, now, ke
         freeAt: number | null;
         lockKey?: any;
         boostPercent: number;
+        weight: bigint;
         rewards: any;
         waiting: string;
         owedUnits: bigint;
@@ -540,16 +563,17 @@ export declare function solanaApp({ spec, rpcUrl, rpc, wallet, programs, now, ke
      * Hands an NFT of any kind to the project until a time (a hold): `seconds` from now, or `{ until }` (Unix seconds).
      * The hold's address names its end. Returns { signature, freeAt }.
      */
-    hold(asset: any, seconds: any): Promise<{
+    hold(asset: any, seconds: any, { acceptLeftover, ...others }?: Readonly<Record<string, any>>): Promise<{
         signature: any;
         freeAt: bigint;
     }>;
     /**
      * A lender's offer to borrow against: `maker`'s offer number `id` in this project. Returns { address, offer, mint,
      * amount, repay, lasts, risks }: `risks`, in words, each power over the loan's token that could make repaying fail
-     * (its freeze authority, a Token-2022 pause, a transfer hook, a permanent delegate) and who holds it. The program
-     * takes such tokens, and a lender who holds one can stop every repayment and take the NFT once it is due: show the
-     * risks before the player borrows.
+     * (its freeze authority, a Token-2022 pause, a transfer hook, a permanent delegate) and who holds it, and each setting
+     * of the token that lets the lender turn the repayment away (accounts that start frozen or can be made to,
+     * confidential transfers) or blocks it (a token that can't be transferred). The program takes such tokens, and a
+     * lender who can stop every repayment takes the NFT once it is due: show the risks before the player borrows.
      */
     loanOffer(maker: any, id: any): Promise<{
         address: any;
@@ -564,10 +588,11 @@ export declare function solanaApp({ spec, rpcUrl, rpc, wallet, programs, now, ke
     /**
      * Borrows against the player's NFT `asset` from `maker`'s offer `id`: the NFT is held until the loan is repaid, or
      * goes to the lender once it is due (`due`, Unix seconds; by default the longest the offer allows, less a minute).
-     * A loan whose token someone could freeze, pause, hook or move (`loanOffer`'s `risks`) is refused unless
-     * `acceptRisks` is true: the page shows the player who holds that power first. `extra`: a transfer hook's accounts.
+     * A loan whose token someone could freeze, pause, hook or move, or whose own settings let the lender turn the
+     * repayment away (`loanOffer`'s `risks`), is refused unless `acceptRisks` is true: the page shows the player each
+     * risk first. `extra`: a transfer hook's accounts.
      */
-    borrow(maker: any, id: any, asset: any, { due, acceptRisks, extra, ...others }?: Readonly<Record<string, any>>): Promise<{
+    borrow(maker: any, id: any, asset: any, { due, acceptRisks, acceptLeftover, extra, ...others }?: Readonly<Record<string, any>>): Promise<{
         signature: any;
         due: any;
         hold: any;
@@ -584,28 +609,35 @@ export declare function solanaApp({ spec, rpcUrl, rpc, wallet, programs, now, ke
         borrower: any;
     } | null>;
     /**
-     * Repays the loan on `asset` (held until `due`), the player's own or a friend's, then sends the NFT home to its
-     * borrower. `repay`: the debt the payer was shown (`loan()`'s, in base units); the program refuses any other
-     * (`TermsChanged`). The repay goes in the wallet's transaction alone, with what it opens (the borrower's Token
-     * Metadata account), so a release that fails never undoes a repay that must land before the loan is due; the same
-     * transaction funds a throwaway key that sends the release (anyone may), a pNFT's or a compressed NFT's too: the key
-     * is funded for what that release opens (a pNFT's token account and record, a compressed NFT's proof record, which
-     * comes back in the same transaction). Returns { signature, released }.
+     * Repays the loan on `asset` (held until `due`), the player's own or a friend's, and brings the NFT home to its
+     * borrower in the same instruction: one prompt. `repay`: the debt the payer was shown (`loan()`'s, in base units);
+     * the program refuses any other (`TermsChanged`). An NFT its collection took back or burned while the project held
+     * it is refused here, before anything is signed: the program takes no repayment for it, and the borrower keeps what
+     * they borrowed. When the NFT can't move now (frozen for now, or its collection refuses the move), or `home` is
+     * false, the money goes alone, so the loan does not fall due: the hold is then over, and anyone sends the NFT home
+     * once it can move (`claims()` lists it). A compressed NFT is proven in the same transaction; the money alone for one
+     * whose proof keeps going out of date goes without it. Returns { signature, home }, and `says` when the NFT waits.
      */
-    repay(asset: any, due: any, { repay, extra, ...others }?: Readonly<Record<string, any>>): Promise<{
+    repay(asset: any, due: any, { repay, home, extra, ...others }?: Readonly<Record<string, any>>): Promise<{
+        says?: undefined;
+        signature: any;
+        home: boolean;
+    } | {
         signature: any;
-        released: any;
+        home: boolean;
+        says: string;
     }>;
     /**
      * Backs `side` of contest number `id` (the authority opens contests while the project runs) with `amount`; a contest
      * of NFTs takes one of the player's NFTs that passes its rule instead (`nft`, its address), held until it is
      * claimed. `listProof`: for a list gate.
      */
-    enter(id: any, side: any, amount: any, { shown, listProof, nft: staked, ...others }?: Readonly<Record<string, any>>): Promise<any>;
+    enter(id: any, side: any, amount: any, { shown, listProof, nft: staked, acceptLeftover, ...others }?: Readonly<Record<string, any>>): Promise<any>;
     /**
      * The auctions: each one's lot, high bid, the least the next bid must be, when it ends and how long is left, and
      * whether the player leads. One no longer on chain has ended. `waiting`: SOL that came back to the player's
-     * wrapped-SOL account from a bid that was topped (`unwrap` turns it into plain SOL).
+     * wrapped-SOL account from a bid that was topped (`unwrap` turns it into plain SOL). `warnings`: what to show every
+     * bidder before a bid (a token whose accounts can be frozen, a lot of another collection).
      */
     auctions(): Promise<any>;
     /**
@@ -614,26 +646,136 @@ export declare function solanaApp({ spec, rpcUrl, rpc, wallet, programs, now, ke
      * wrapped-SOL account does not hold already is wrapped, and the account stays open: if this bid is topped, it comes
      * back there.
      */
-    bid(auctionKey: any, amount: any, { shown, listProof, nfts, ...others }?: Readonly<Record<string, any>>): Promise<any>;
+    bid(auctionKey: any, amount: any, { shown, listProof, nfts, acceptLeftover, ...others }?: Readonly<Record<string, any>>): Promise<any>;
     /**
-     * Ends an auction that is over (anyone can; the winner usually does): the lot to the highest bidder, a new
-     * collectible minted for them at the address its item and serial name, however long after the end it is sent. A
-     * roll lot makes the winner's roll of its box (`order`), which `collect` asks for and settles. An end too big for one
-     * transaction makes each NFT a hold and sends each home with a release after it (`releases`).
+     * Ends an auction that is over (anyone can; the winner usually does): the lot to the highest bidder and the winning
+     * bid to whoever owned it, in one transaction (a new collectible minted for the winner at the address its item and
+     * serial name), however long after the end it is sent. A roll lot makes the winner's roll of its box (`order`), which
+     * `collect` asks for and settles. An NFT lot whose end can't fit one transaction (a compressed lot's long proof, many
+     * shares, a hooked coin) goes first, and the bid is paid by a second end, the accounts it pays into opened before it.
+     * When the lot can't move now (its collection froze it or refuses the move), nothing is sent: the sale waits, the
+     * winning bid in the project's vault (`{ waiting: true, says }`); end it again later, or the project's keys call it
+     * off (`callOffSale`). When the lot or an NFT of the winning bid is gone (its collection took it back or burned it),
+     * the sale is called off on that evidence, which anyone may: the bid goes back to its bidder (`{ calledOff: true }`).
+     * With no bid, the lot goes home to its seller. An end too big for one transaction otherwise makes each NFT that may
+     * be a hold one, and sends each on with a release after it (`releases`).
      */
     endAuction(auctionKey: any, { holders, ...others }?: Readonly<Record<string, any>>): Promise<{
-        signature: any;
+        says?: undefined;
+        owedPaid: any;
+        waiting?: undefined;
+        paid: any;
+        releases?: undefined;
+    } | {
         owedPaid: any;
+        waiting?: undefined;
+        paid: null;
+        says: string;
+        releases?: undefined;
     } | {
-        owedPaid?: undefined;
+        says?: undefined;
+        owedPaid: any;
+        waiting?: undefined;
+        paid: any;
+        releases: any[];
+    } | {
+        winner?: any;
+        asset?: any;
         signature: any;
         releases: any[];
+    } | {
+        waiting: boolean;
+        says: string;
+    } | {
+        says?: undefined;
         winner?: any;
+        asset?: any;
+        waiting?: undefined;
+        signature: any;
+        order?: any;
+        rolled?: {
+            order: any;
+            settled: string;
+            says: string;
+        } | {
+            order: any;
+            settled: null;
+            says: string;
+        } | {
+            says?: undefined;
+            order: any;
+            won: any;
+            assets: any;
+            settled: any;
+            parts?: any[] | undefined;
+            asset?: any;
+        } | undefined;
+    } | {
+        says?: undefined;
+        winner?: any;
+        asset?: any;
+        waiting?: undefined;
+        signature: any;
+        lotFirst: boolean;
+        paid: any;
+        releases?: undefined;
+    } | {
+        winner?: any;
+        asset?: any;
+        waiting?: undefined;
+        signature: any;
+        lotFirst: boolean;
+        paid: null;
+        says: string;
+        releases?: undefined;
+    } | {
+        says?: undefined;
+        winner?: any;
+        asset?: any;
+        waiting?: undefined;
+        signature: any;
+        lotFirst: boolean;
+        paid: any;
+        releases: any[];
+    }>;
+    /**
+     * The project's owner or authority calls off the sale of an NFT lot whose auction is over and whose lot has not moved
+     * (one that never thaws, say), for the project fee: the winning bid goes back to its bidder and the lot home to its
+     * seller, each moved, or made a hold that anyone sends on once it can move (`releases`). Anyone may when the lot or
+     * an NFT of the winning bid is gone (`endAuction` does it then). Refused once the lot went to its winner (`CantCallOff`).
+     */
+    callOffSale(auctionKey: any, { ...others }?: Readonly<Record<string, any>>): Promise<{
+        says?: undefined;
+        owedPaid: any;
+        waiting?: undefined;
+        paid: any;
+        releases?: undefined;
     } | {
-        owedPaid?: undefined;
+        owedPaid: any;
+        waiting?: undefined;
+        paid: null;
+        says: string;
+        releases?: undefined;
+    } | {
+        says?: undefined;
+        owedPaid: any;
+        waiting?: undefined;
+        paid: any;
+        releases: any[];
+    } | {
+        winner?: any;
+        asset?: any;
         signature: any;
+        releases: any[];
+    } | {
+        waiting: boolean;
+        says: string;
+    } | {
+        says?: undefined;
         winner?: any;
         asset?: any;
+        waiting?: undefined;
+        signature: any;
         order?: any;
         rolled?: {
             order: any;
@@ -652,6 +794,33 @@ export declare function solanaApp({ spec, rpcUrl, rpc, wallet, programs, now, ke
             parts?: any[] | undefined;
             asset?: any;
         } | undefined;
+    } | {
+        says?: undefined;
+        winner?: any;
+        asset?: any;
+        waiting?: undefined;
+        signature: any;
+        lotFirst: boolean;
+        paid: any;
+        releases?: undefined;
+    } | {
+        winner?: any;
+        asset?: any;
+        waiting?: undefined;
+        signature: any;
+        lotFirst: boolean;
+        paid: null;
+        says: string;
+        releases?: undefined;
+    } | {
+        says?: undefined;
+        winner?: any;
+        asset?: any;
+        waiting?: undefined;
+        signature: any;
+        lotFirst: boolean;
+        paid: any;
+        releases: any[];
     }>;
     /**
      * Runs a schedule that is due (an emission into a pool, a rent or a drip): the project's owner or authority, or who it
@@ -664,12 +833,12 @@ export declare function solanaApp({ spec, rpcUrl, rpc, wallet, programs, now, ke
      * Lists one of the player's NFTs (any kind) for sale at `price` (whole units of `currency`, the economy's by
      * default), `shares` taken first (a royalty, a platform's cut). The project holds it until it sells or is unlisted.
      */
-    listForSale(asset: any, { price, currency, shares, ...others }?: Readonly<Record<string, any>>): Promise<any>;
+    listForSale(asset: any, { price, currency, shares, acceptLeftover, ...others }?: Readonly<Record<string, any>>): Promise<any>;
     /**
      * Lists one of the player's NFTs for rent: `price` (whole units) a period of `lasts` seconds, a renter taking 1 to
      * `maxPeriods` at once. Nobody can end a rental early; the next renter takes it once one is over, until it is unlisted.
      */
-    listForRent(asset: any, { price, lasts, maxPeriods, currency, shares, ...others }?: Readonly<Record<string, any>>): Promise<any>;
+    listForRent(asset: any, { price, lasts, maxPeriods, currency, shares, acceptLeftover, ...others }?: Readonly<Record<string, any>>): Promise<any>;
     /** The listing of `asset` (one account read), or null: { listing, asset, maker, mint, deal, renter, until }. */
     listing(asset: any): Promise<any>;
     /** Who rents `asset` now (one account read, then a check that the project still holds it), or null. */
@@ -736,110 +905,7 @@ export declare function solanaApp({ spec, rpcUrl, rpc, wallet, programs, now, ke
      * a winner's first claim of a contest of tokens carries `potUnits` and `prizeUnits`, its part as the decision wrote
      * it (base units, as text). Pass one to `claim`.
      */
-    claims(): Promise<({
-        key?: undefined;
-        tree?: undefined;
-        kind: string;
-        order: any;
-        says: string;
-        hold?: undefined;
-        round?: undefined;
-        pulls?: undefined;
-        asset?: undefined;
-        table?: undefined;
-    } | {
-        key?: undefined;
-        tree?: undefined;
-        order?: undefined;
-        kind: string;
-        id: any;
-        side: any;
-        says: string;
-        potUnits?: string | undefined;
-        prizeUnits?: string | undefined;
-        hold?: undefined;
-        round?: undefined;
-        pulls?: undefined;
-        asset?: undefined;
-        table?: undefined;
-    } | {
-        key?: undefined;
-        tree?: undefined;
-        order?: undefined;
-        kind: string;
-        asset: any;
-        hold: any;
-        says: string;
-        round?: undefined;
-        pulls?: undefined;
-        table?: undefined;
-    } | {
-        key?: undefined;
-        order?: undefined;
-        hold?: undefined;
-        kind: string;
-        asset: string;
-        tree: string;
-        says: string;
-        round?: undefined;
-        pulls?: undefined;
-        table?: undefined;
-    } | {
-        tree?: undefined;
-        order?: undefined;
-        hold?: undefined;
-        kind: string;
-        key: any;
-        says: string;
-        round?: undefined;
-        pulls?: undefined;
-        asset?: undefined;
-        table?: undefined;
-    } | {
-        tree?: undefined;
-        order?: undefined;
-        hold?: undefined;
-        kind: string;
-        key: any;
-        round: any;
-        says: string;
-        pulls?: undefined;
-        asset?: undefined;
-        table?: undefined;
-    } | {
-        tree?: undefined;
-        order?: undefined;
-        hold?: undefined;
-        kind: string;
-        key: any;
-        round: any;
-        pulls: any;
-        says: string;
-        asset?: undefined;
-        table?: undefined;
-    } | {
-        key?: undefined;
-        tree?: undefined;
-        order?: undefined;
-        hold?: undefined;
-        round?: undefined;
-        pulls?: undefined;
-        kind: string;
-        asset: any;
-        says: string;
-        table?: undefined;
-    } | {
-        key?: undefined;
-        tree?: undefined;
-        order?: undefined;
-        hold?: undefined;
-        round?: undefined;
-        pulls?: undefined;
-        asset?: undefined;
-        kind: string;
-        table: any;
-        says: string;
-    })[]>;
+    claims(): Promise<any[]>;
     /**
      * Finishes one of `claims()`, signed by this player. Returns the signature. A winner of a contest of NFTs picks
      * which loser's NFT they take (`{ take: asset }`, the NFT of a losing entry that still holds one; the first found by default):