@metaplex-foundation/genesis 0.12.4

package/README.md

@@ -0,0 +1,16 @@
+# JavaScript client for Genesis
+
+A Umi-compatible JavaScript library for the project.
+
+## Getting started
+
+1. First, if you're not already using Umi, [follow these instructions to install the Umi framework](https://github.com/metaplex-foundation/umi/blob/main/docs/installation.md).
+2. Next, install this library using the package manager of your choice.
+   ```sh
+   npm install @metaplex-foundation/genesis
+   ```
+2. Finally, register the library with your Umi instance like so.
+   ```ts
+   import { genesis } from '@metaplex-foundation/genesis';
+   umi.use(genesis());
+   ```

package/dist/src/allowlist.d.ts

@@ -0,0 +1,18 @@
+import { PublicKey } from '@metaplex-foundation/umi';
+import { PresaleBucketV1 } from './generated';
+export type AllowlistMember = {
+    address: PublicKey;
+};
+export declare function prepareAllowlist(recipients: Array<AllowlistMember>): {
+    root: Uint8Array;
+    proofs: Uint8Array[][];
+    treeHeight: number;
+};
+export declare function getAllowlistLeafBytes(recipient: AllowlistMember): Uint8Array;
+/**
+ * Computes the minimum Merkle tree height required to accommodate the given
+ * number of leaves. The height is defined as the number of internal layers
+ * above the leaves (i.e. a tree with a single leaf has height 0).
+ */
+export declare function computeTreeHeight(leavesCount: number): number;
+export declare function isAllowlistActive(presaleBucket: PresaleBucketV1): boolean;

package/dist/src/allowlist.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAllowlistActive = exports.computeTreeHeight = exports.getAllowlistLeafBytes = exports.prepareAllowlist = void 0;
+const umi_1 = require("@metaplex-foundation/umi");
+const merkleTree_1 = require("./merkleTree");
+function prepareAllowlist(recipients) {
+    const leafs = recipients.map(getAllowlistLeafBytes);
+    const tree = (0, merkleTree_1.createMerkleTree)(leafs);
+    const merkleRoot = (0, merkleTree_1.getRoot)(tree);
+    // Calculate the minimum tree height required for the number of recipients.
+    const treeHeight = computeTreeHeight(leafs.length);
+    return {
+        root: merkleRoot,
+        proofs: leafs.map((_, i) => (0, merkleTree_1.getProof)(tree, i)),
+        treeHeight,
+    };
+}
+exports.prepareAllowlist = prepareAllowlist;
+function getAllowlistLeafBytes(recipient) {
+    const pubkey = (0, umi_1.publicKey)(recipient.address);
+    const pubkeyBytes = (0, umi_1.publicKeyBytes)(pubkey);
+    return pubkeyBytes;
+}
+exports.getAllowlistLeafBytes = getAllowlistLeafBytes;
+/**
+ * Computes the minimum Merkle tree height required to accommodate the given
+ * number of leaves. The height is defined as the number of internal layers
+ * above the leaves (i.e. a tree with a single leaf has height 0).
+ */
+function computeTreeHeight(leavesCount) {
+    if (leavesCount <= 1)
+        return 0;
+    // Double the capacity at each level. Using log2 to calculate the number of doublings required.
+    return Math.ceil(Math.log2(leavesCount));
+}
+exports.computeTreeHeight = computeTreeHeight;
+function isAllowlistActive(presaleBucket) {
+    if (!presaleBucket.hasAllowlist) {
+        return false;
+    }
+    if (presaleBucket.allowlistEnd < BigInt(Date.now() * 1000)) {
+        return false;
+    }
+    if (presaleBucket.isAllowlistSolCapReached) {
+        return false;
+    }
+    return true;
+}
+exports.isAllowlistActive = isAllowlistActive;
+//# sourceMappingURL=allowlist.js.map

package/dist/src/allowlist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"allowlist.js","sourceRoot":"","sources":["../../src/allowlist.ts"],"names":[],"mappings":";;;AAAA,kDAAgF;AAChF,6CAAmE;AAOnE,SAAgB,gBAAgB,CAAC,UAAkC;IACjE,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;IACpD,MAAM,IAAI,GAAG,IAAA,6BAAgB,EAAC,KAAK,CAAC,CAAC;IACrC,MAAM,UAAU,GAAG,IAAA,oBAAO,EAAC,IAAI,CAAC,CAAC;IAEjC,2EAA2E;IAC3E,MAAM,UAAU,GAAG,iBAAiB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACnD,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAA,qBAAQ,EAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAC9C,UAAU;KACX,CAAC;AACJ,CAAC;AAZD,4CAYC;AAED,SAAgB,qBAAqB,CAAC,SAA0B;IAC9D,MAAM,MAAM,GAAG,IAAA,eAAS,EAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAC5C,MAAM,WAAW,GAAG,IAAA,oBAAc,EAAC,MAAM,CAAC,CAAC;IAE3C,OAAO,WAAW,CAAC;AACrB,CAAC;AALD,sDAKC;AAED;;;;GAIG;AACH,SAAgB,iBAAiB,CAAC,WAAmB;IACnD,IAAI,WAAW,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAE/B,+FAA+F;IAC/F,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;AAC3C,CAAC;AALD,8CAKC;AAED,SAAgB,iBAAiB,CAAC,aAA8B;IAC9D,IAAI,CAAC,aAAa,CAAC,YAAY,EAAE;QAC/B,OAAO,KAAK,CAAC;KACd;IAED,IAAI,aAAa,CAAC,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,EAAE;QAC1D,OAAO,KAAK,CAAC;KACd;IAED,IAAI,aAAa,CAAC,wBAAwB,EAAE;QAC1C,OAAO,KAAK,CAAC;KACd;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAdD,8CAcC"}

package/dist/src/auction.d.ts

@@ -0,0 +1,296 @@
+import { Context, MicroSolAmount, SolAmount } from '@metaplex-foundation/umi';
+import { AuctionAVLTreeV1, AuctionBucketV1 } from './generated';
+import { AuctionNode, TreeBid } from './hooked';
+export declare const MICRO_LAMPORTS_PER_LAMPORT = 1000000;
+/**
+ * Converts lamports to micro-lamports for auction pricing.
+ *
+ * Auction bids use micro-lamports (1/1,000,000 of a lamport) for sub-lamport precision.
+ * This allows for finer granularity in token pricing.
+ *
+ * @param lamports - The amount in lamports to convert
+ * @returns The equivalent amount in micro-lamports
+ *
+ * @example
+ * ```typescript
+ * // 0.5 SOL per token = 500,000,000 lamports per token
+ * const pricePerToken = lamportsToUlamports(500_000_000);
+ *
+ * // Use in auction bid
+ * await placeAuctionBidV1(umi, {
+ *   // ... other params
+ *   pricePerToken,
+ *   // ...
+ * }).sendAndConfirm(umi);
+ * ```
+ */
+export declare function lamportsToUlamports(lamportsInput: number | bigint): bigint;
+/**
+ * Retrieves all nodes from an auction AVL tree.
+ *
+ * @param tree - The auction AVL tree to extract nodes from
+ * @returns An array of all auction nodes in the tree, in allocation order
+ *
+ * @example
+ * ```typescript
+ * const tree = await fetchAuctionAVLTreeV1(umi, treePda);
+ * const allNodes = getAllAuctionTreeNodes(tree);
+ * console.log(`Tree contains ${allNodes.length} nodes`);
+ * ```
+ */
+export declare function getAllAuctionTreeNodes(tree: AuctionAVLTreeV1): AuctionNode[];
+/**
+ * Retrieves a specific node from an auction AVL tree by its index.
+ *
+ * @param tree - The auction AVL tree to search in
+ * @param index - The 1-based index of the node to retrieve
+ * @returns The auction node at the specified index, or null if index is out of bounds
+ *
+ * @example
+ * ```typescript
+ * const tree = await fetchAuctionAVLTreeV1(umi, treePda);
+ * const node = getAuctionTreeNode(tree, 5);
+ * if (node) {
+ *   console.log(`Node 5 bid: ${node.bid.pricePerToken}`);
+ * }
+ * ```
+ */
+export declare function getAuctionTreeNode(tree: AuctionAVLTreeV1, index: number): AuctionNode | null;
+/**
+ * Finds all bids in the auction tree that meet or exceed the clearing price.
+ *
+ * Uses an in-order traversal of the AVL tree to efficiently collect qualifying bids.
+ * The function traverses from highest to lowest prices and stops when prices fall
+ * below the clearing price threshold.
+ *
+ * @param tree - The auction AVL tree containing all bids
+ * @param clearingPriceULamports - The minimum price in micro-lamports for a bid to qualify
+ * @returns Array of bids that meet or exceed the clearing price, sorted by price (highest first)
+ *
+ * @example
+ * ```typescript
+ * const tree = await fetchAuctionAVLTreeV1(umi, treePda);
+ * const clearingPrice = lamportsToMicroLamports(1_000_000); // 0.001 SOL
+ * const qualifyingBids = findAuctionBids(tree, clearingPrice);
+ * ```
+ */
+export declare function findAuctionBids(tree: AuctionAVLTreeV1, clearingPriceULamports: bigint): TreeBid[];
+/**
+ * Calculates the winning bids for an auction based on clearing price and token allocation.
+ *
+ * This function determines which bids win tokens in the auction by:
+ * 1. Finding all bids at or above the clearing price
+ * 2. Sorting them by price (highest first) and bid number (earliest first for ties)
+ * 3. Allocating tokens until the supply is exhausted
+ *
+ * @param tree - The auction AVL tree containing all bids
+ * @param clearingPriceULamports - The clearing price in micro-lamports
+ * @param tokenAllocation - The total number of tokens available for distribution
+ * @returns Array of winning bids in order of priority
+ *
+ * @example
+ * ```typescript
+ * const tree = await fetchAuctionAVLTreeV1(umi, treePda);
+ * const clearingPrice = lamportsToMicroLamports(500_000_000); // 0.5 SOL
+ * const tokenSupply = 1_000_000n;
+ * const winners = calculateAuctionWinners(tree, clearingPrice, tokenSupply);
+ * ```
+ */
+export declare function calculateAuctionWinners(tree: AuctionAVLTreeV1, clearingPriceULamports: bigint, tokenAllocation: bigint): TreeBid[];
+/**
+ * Fetches all winning bids from an auction bucket.
+ *
+ * This async function retrieves the auction tree associated with a bucket
+ * and calculates the winning bids based on the bucket's clearing price
+ * and token allocation.
+ *
+ * @param umi - Umi context containing RPC, programs, and eddsa for Solana interaction
+ * @param auction - The auction bucket containing clearing price and allocation info
+ * @returns Promise resolving to an array of winning bids
+ * @throws Error if the auction tree is not found
+ *
+ * @example
+ * ```typescript
+ * const auctionBucket = await fetchAuctionBucketV1(umi, bucketPda);
+ * const winners = await getAuctionWinners(umi, auctionBucket);
+ * console.log(`${winners.length} winning bids found`);
+ * ```
+ */
+export declare function fetchAuctionWinners(umi: Pick<Context, 'eddsa' | 'rpc' | 'programs'>, auction: AuctionBucketV1): Promise<TreeBid[]>;
+export type MicroSolInput = bigint | MicroSolAmount;
+/**
+ * Creates a MicroSolAmount from either a bigint or an existing MicroSolAmount.
+ *
+ * @param amount - The amount as bigint or MicroSolAmount
+ * @returns A MicroSolAmount object
+ * @internal
+ */
+export declare function createMicroLamports(amount: MicroSolInput): MicroSolAmount;
+export type AuctionBucketV1Input = Omit<AuctionBucketV1, 'clearingPriceUlamports' | 'minPriceUlamports'> & {
+    clearingPriceUlamports: MicroSolInput;
+    minPriceUlamports: MicroSolInput;
+};
+export type BidInput = Omit<TreeBid, 'priceUlamports'> & {
+    priceUlamports: MicroSolInput;
+};
+/**
+ * Determines if a bid is winning based on the auction's clearing price and bid number.
+ *
+ * A bid is considered winning if:
+ * - Its price exceeds the clearing price, OR
+ * - Its price equals the clearing price AND its bid number is at or before the clearing price bid number
+ *
+ * @param auction - The auction bucket with clearing price and clearing price bid number
+ * @param bid - The bid to check with price per token and bid number
+ * @returns True if the bid is winning, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const auction = await fetchAuctionBucketV1(umi, auctionPda);
+ * const bid = await fetchAuctionBidV1(umi, bidPda);
+ * const isWinner = isBidWinning(auction, bid); // true (price exceeds clearing)
+ * ```
+ */
+export declare function isBidWinning(auction: Pick<AuctionBucketV1Input, 'clearingPriceBidNumber' | 'clearingPriceUlamports'>, bid: Pick<BidInput, 'bidNumber' | 'priceUlamports'>): boolean;
+/**
+ * Determines if a bid is losing (not winning) in the auction.
+ *
+ * This is the inverse of isBidWinning - a bid is losing if it doesn't meet
+ * the criteria for winning.
+ *
+ * @param auction - The auction bucket with clearing price and clearing price bid number
+ * @param bid - The bid to check with price per token and bid number
+ * @returns True if the bid is losing, false if winning
+ *
+ * @example
+ * ```typescript
+ * const auction = await fetchAuctionBucketV1(umi, auctionPda);
+ * const bid = await fetchAuctionBidV1(umi, bidPda);
+ * const isLoser = isBidLosing(auction, bid); // true (price below clearing)
+ * ```
+ */
+export declare function isBidLosing(auction: Pick<AuctionBucketV1Input, 'clearingPriceUlamports' | 'clearingPriceBidNumber'>, bid: Pick<BidInput, 'priceUlamports' | 'bidNumber'>): boolean;
+/**
+ * Determines if a bid is partially filled at the clearing price.
+ *
+ * A bid is considered partially filled when:
+ * - The bid is at the clearing price (bid number matches clearing price bid number)
+ * - The bid requests more tokens than are available at the clearing price
+ *
+ * This occurs when the auction's token supply is exhausted at the clearing price,
+ * causing the last bid at that price to receive only a portion of their requested tokens.
+ *
+ * @param auctionBucket - The auction bucket with clearing price bid number and allocation
+ * @param bid - The bid to check with bid number and requested token quantity
+ * @returns True if the bid is partially filled, false if fully filled or not at clearing price
+ *
+ * @example
+ * ```typescript
+ * const auction = await fetchAuctionBucketV1(umi, auctionPda);
+ * const bid = await fetchAuctionBidV1(umi, bidPda);
+ * const isPartial = isBidPartiallyFilled(auction, bid); // true (partial fill at clearing price)
+ * ```
+ */
+export declare function isBidPartiallyFilled(auctionBucket: Pick<AuctionBucketV1Input, 'clearingPriceBidNumber' | 'clearingPriceAllocation'>, bid: Pick<BidInput, 'bidNumber' | 'tokenQuantity'>): boolean;
+/**
+ * Calculates the actual token amount a bid will receive.
+ *
+ * Returns either the partial fill amount (if bid is at clearing price) or
+ * the full token quantity requested by the bid.
+ *
+ * @param bid - The bid with bid number and requested token quantity
+ * @param auctionBucket - The auction bucket with clearing price info
+ * @returns The actual number of tokens the bid will receive
+ *
+ * @example
+ * ```typescript
+ * const bid = await fetchAuctionBidV1(umi, bidPda);
+ * const auction = await fetchAuctionBucketV1(umi, auctionPda);
+ * const fillAmount = getBidFillAmount(bid, auction); // 50000n (partial fill)
+ * ```
+ */
+export declare function getBidFillAmount(auctionBucket: Pick<AuctionBucketV1Input, 'clearingPriceBidNumber' | 'clearingPriceAllocation'>, bid: Pick<BidInput, 'bidNumber' | 'tokenQuantity'>): bigint;
+/**
+ * Converts SOL amount to micro-SOL (µSOL) amount.
+ *
+ * @param sol - The amount in SOL (lamports)
+ * @returns The equivalent amount in micro-SOL (micro-lamports)
+ *
+ * @example
+ * ```typescript
+ * const solAmount = lamports(1_000_000_000); // 1 SOL
+ * const microSolAmount = toUSol(solAmount); // 1,000,000,000,000,000 µSOL
+ * ```
+ */
+export declare function toUSol(sol: SolAmount): MicroSolAmount;
+/**
+ * Converts micro-SOL (µSOL) amount to SOL amount.
+ *
+ * @param uSol - The amount in micro-SOL (micro-lamports)
+ * @returns The equivalent amount in SOL (lamports)
+ *
+ * @example
+ * ```typescript
+ * const microSolAmount = microLamports(1_000_000_000_000_000n); // 1,000,000,000,000,000 µSOL
+ * const solAmount = toSol(microSolAmount); // 1 SOL
+ * ```
+ */
+export declare function toSol(uSol: MicroSolAmount): SolAmount;
+/**
+ * Calculates the micro-SOL price per token basis unit.
+ *
+ * Converts a SOL per token price to micro-SOL per smallest token unit,
+ * accounting for token decimals. This is used for precise sub-lamport pricing.
+ *
+ * @param solPerTokenInput - The price in SOL per whole token (or lamports as bigint)
+ * @param tokenDecimals - The number of decimal places for the token
+ * @returns The price in micro-SOL per token basis unit
+ *
+ * @example
+ * ```typescript
+ * // For a token with 6 decimals, priced at 0.5 SOL per token
+ * const priceUlamports = lamports(500_000_000); // 0.5 SOL
+ * const microSolPerBasis = uSolPerTokenBasis(priceUlamports, 6);
+ * // Returns price per smallest token unit (1/1,000,000 of a token)
+ * ```
+ */
+export declare function uSolPerTokenBasis(solPerTokenInput: SolAmount | bigint, tokenDecimals: number): MicroSolAmount;
+/**
+ * Converts micro-SOL per token basis unit to SOL per whole token.
+ *
+ * Takes a price in micro-SOL per smallest token unit and converts it to
+ * SOL per whole token, accounting for token decimals.
+ *
+ * @param ulamportsPerTokenBasis - The price in micro-SOL per token basis unit
+ * @param tokenDecimals - The number of decimal places for the token
+ * @returns The price in SOL per whole token
+ *
+ * @example
+ * ```typescript
+ * // For a token with 6 decimals
+ * const microSolPerBasis = microLamports(500n); // Price per smallest unit
+ * const solPerWholeToken = solPerToken(microSolPerBasis, 6);
+ * // Returns price in SOL for one whole token
+ * ```
+ */
+export declare function solPerToken(ulamportsPerTokenBasis: MicroSolInput, tokenDecimals: number): SolAmount;
+/**
+ * Calculates the total SOL cost for a bid.
+ *
+ * Multiplies the micro-SOL price per token basis by the token amount
+ * to get the total cost in SOL.
+ *
+ * @param pricePerTokenBasis - The price in micro-SOL per token basis unit
+ * @param tokenAmount - The number of token basis units to purchase
+ * @returns The total cost in SOL
+ *
+ * @example
+ * ```typescript
+ * // Bidding for 1,000,000 token units at 500 micro-SOL each
+ * const pricePerUnit = microLamports(500n);
+ * const amount = 1_000_000n;
+ * const totalCost = totalBidSol(pricePerUnit, amount);
+ * // Returns total SOL needed for the bid
+ * ```
+ */
+export declare function totalBidSol(pricePerTokenBasis: MicroSolInput, tokenAmount: bigint): SolAmount;