docs: initial documentation

package.json

@@ -28,6 +28,7 @@
   },
   "scripts": {
     "doc": "typedoc",
+    "doc:watch": "typedoc --watch",
     "doc:update": "yarn doc && ./sh/publish-docs",
     "build": "rimraf lib && rollup -c",
     "dev": "rollup -c --watch",

src/actions/burnToken.ts

@@ -5,35 +5,44 @@ import { sendTransaction } from './transactions';
 import { Transaction } from '@metaplex-foundation/mpl-core';
 import { Token, TOKEN_PROGRAM_ID, u64 } from '@solana/spl-token';
 
-interface IBurnTokenParams {
+/** Parameters for {@link burnToken} **/
+export interface BurnTokenParams {
   connection: Connection;
+  /** Will be used as the fee payer and as the `owner` if none is specified. If ${@link close} is left as its' default `true` value, the `wallet` parameter will also serve as the destination wallet to refund rent exemption SOL lamports to. **/
   wallet: Wallet;
-  token: PublicKey;
+  /** The associated token account containing the tokens to be burned **/
+  account: PublicKey;
+  /** The mint account of the token to be burned **/
   mint: PublicKey;
+  /** Amount of tokens (accounting for decimals) to burn. One important nuance to remember is that each token mint has a different amount of decimals, which need to be accounted while specifying the amount. For instance, to burn 1 token with a 0 decimal mint you would provide `1` as the amount, but for a token mint with 6 decimals you would provide `1000000` as the amount to burn one whole token **/
   amount: number | u64;
+  /** The owner authority of the associated token account containing the burnt tokens **/
   owner?: PublicKey;
-  // close token account after
+  /** Set to `true` if you wish to close the token account after burning the token **/
   close?: boolean;
 }
 
-interface IBurnTokenResponse {
+export interface BurnTokenResponse {
   txId: string;
 }
 
+/**
+ * Burns token of the given mint and optionally closes the associated token account. Please note that by default this action attempts to close the account after burning tokens, which will fail if not all the tokens contained in the account were burned. If you want to burn only part of the account balance, make sure you set `close` to `false`.
+ */
 export const burnToken = async ({
   connection,
   wallet,
-  token,
+  account,
   mint,
   amount,
   owner,
   close = true,
-}: IBurnTokenParams): Promise<IBurnTokenResponse> => {
+}: BurnTokenParams): Promise<BurnTokenResponse> => {
   const tx = new Transaction({ feePayer: wallet.publicKey }).add(
     Token.createBurnInstruction(
       TOKEN_PROGRAM_ID,
       mint,
-      token,
+      account,
       owner ?? wallet.publicKey,
       [],
       amount,
@@ -44,7 +53,7 @@ export const burnToken = async ({
     tx.add(
       Token.createCloseAccountInstruction(
         TOKEN_PROGRAM_ID,
-        token,
+        account,
         wallet.publicKey,
         owner ?? wallet.publicKey,
         [],

src/actions/cancelBid.ts

@@ -14,25 +14,35 @@ import { AuctionManager } from '@metaplex-foundation/mpl-metaplex';
 import { CreateTokenAccount } from '../transactions';
 import { Transaction } from '@metaplex-foundation/mpl-core';
 
-interface ICancelBidParams {
+/**
+ * Parameters for {@link cancelBid}
+ */
+export interface CancelBidParams {
   connection: Connection;
+  /** Wallet of the original bidder **/
   wallet: Wallet;
+  /** Program account of the auction for the bid to be cancelled **/
   auction: PublicKey;
+  /** SPL associated token account where the tokens are deposited **/
   bidderPotToken: PublicKey;
+  /** The bidders token account they'll receive refund with **/
   destAccount?: PublicKey;
 }
 
-interface ICancelBidResponse {
+export interface CancelBidResponse {
   txId: string;
 }
 
+/**
+ * Cancel a bid on a running auction. Any bidder can cancel any time during an auction, but only non-winners of the auction can cancel after it ends. When users cancel, they receive full refunds.
+ */
 export const cancelBid = async ({
   connection,
   wallet,
   auction,
   bidderPotToken,
   destAccount,
-}: ICancelBidParams): Promise<ICancelBidResponse> => {
+}: CancelBidParams): Promise<CancelBidResponse> => {
   const bidder = wallet.publicKey;
   const auctionManager = await AuctionManager.getPDA(auction);
   const manager = await AuctionManager.load(connection, auctionManager);
@@ -70,7 +80,7 @@ export const cancelBid = async ({
   return { txId };
 };
 
-interface ICancelBidTransactionsParams {
+interface CancelBidTransactionsParams {
   destAccount?: PublicKey;
   bidder: PublicKey;
   accountRentExempt: number;
@@ -94,7 +104,7 @@ export const getCancelBidTransactions = async ({
   auctionExtended,
   auctionTokenMint,
   vault,
-}: ICancelBidTransactionsParams): Promise<TransactionsBatch> => {
+}: CancelBidTransactionsParams): Promise<TransactionsBatch> => {
   const txBatch = new TransactionsBatch({ transactions: [] });
   if (!destAccount) {
     const account = Keypair.generate();

src/actions/claimBid.ts

@@ -6,25 +6,35 @@ import { Auction, AuctionExtended, BidderPot } from '@metaplex-foundation/mpl-au
 import { TransactionsBatch } from '../utils/transactions-batch';
 import { AuctionManager, ClaimBid } from '@metaplex-foundation/mpl-metaplex';
 
-interface IClaimBidParams {
+/**
+ * Parameters for {@link claimBid}
+ */
+export interface ClaimBidParams {
   connection: Connection;
+  /** Wallet of the bidder the bid that is being cancelled belongs to **/
   wallet: Wallet;
+  /** The address of the auction program account for the bid that is being cancelled **/
   auction: PublicKey;
+  /** The address of the store the auction manager the bid is being cancelled on belongs to **/
   store: PublicKey;
+  /** Bidder pot SPL associated token account **/
   bidderPotToken: PublicKey;
 }
 
-interface IClaimBidResponse {
+export interface ClaimBidResponse {
   txId: string;
 }
 
+/**
+ * Claim a winning bid as the auctioneer. Pulling money out of the auction contract as an auctioneer can only be done after an auction has ended and must be done for each winning bid, one after the other.
+ */
 export const claimBid = async ({
   connection,
   wallet,
   store,
   auction,
   bidderPotToken,
-}: IClaimBidParams): Promise<IClaimBidResponse> => {
+}: ClaimBidParams): Promise<ClaimBidResponse> => {
   // get data for transactions
   const bidder = wallet.publicKey;
   const auctionManager = await AuctionManager.getPDA(auction);

src/actions/createMasterEdition.ts

@@ -8,17 +8,28 @@ import {
 import { sendTransaction } from './transactions';
 import BN from 'bn.js';
 
-interface CreateMasterEditionParams {
+/** Parameters for {@link createMasterEdition} **/
+export interface CreateMasterEditionParams {
   connection: Connection;
+  /** The signer and fee payer for the operation. This wallet must be the same signer used to create the {@link Metadata} program account. **/
   wallet: Wallet;
+  /** This has to be the same mint provided when creating the {@link Metadata} program account and that account must already exist prior to creating the {@link MasterEdition} account. **/
   editionMint: PublicKey;
+  /**
+   * You can optionally specify an updateAuthority different from the provided {@link wallet}
+   * @default The updateAuthority will be set to the provided {@link wallet} address if not otherwise specified.
+   **/
   updateAuthority?: PublicKey;
   maxSupply?: BN;
 }
 
-/*
- * NOTE 1: a metadata account must already exist
- * NOTE 2: must have exactly 1 editionMint token with 0 decimals outstanding
+/**
+ * Creates a MasterEdition program account.
+ *
+ * Please note that for this action to execute successfully:
+ * 1. A metadata account must already exist
+ * 2. There must be exactly 1 editionMint token with 0 decimals outstanding
+ * @return This action returns the resulting transaction id once it has been executed
  */
 export const createMasterEdition = async (
   { connection, wallet, editionMint, updateAuthority, maxSupply } = {} as CreateMasterEditionParams,

src/actions/createMetadata.ts

@@ -7,14 +7,27 @@ import {
 } from '@metaplex-foundation/mpl-token-metadata';
 import { sendTransaction } from './transactions';
 
-interface CreateMetadataParams {
+/**
+ * Parameters for {@link createMetadata}
+ */
+export interface CreateMetadataParams {
   connection: Connection;
+  /** Will be used as the fee payer, mint authority and a default update authority if {@link updateAuthority} isn't specified **/
   wallet: Wallet;
-  editionMint: PublicKey; // can be any mint with 0 decimals
+  /** Can be any mint with 0 decimals **/
+  editionMint: PublicKey;
   metadataData: MetadataDataData;
+  /**
+   * You can optionally specify an updateAuthority different from the provided {@link wallet}
+   * @default The updateAuthority will be set to the provided {@link wallet} address if not otherwise specified.
+   **/
   updateAuthority?: PublicKey;
 }
 
+/**
+ * Creates a Metadata program account. This action is used in {@link mintNFT}.
+ * @return This action returns the resulting transaction id once it has been executed
+ */
 export const createMetadata = async (
   { connection, wallet, editionMint, metadataData, updateAuthority } = {} as CreateMetadataParams,
 ): Promise<string> => {

src/actions/initStore.ts

@@ -4,22 +4,32 @@ import { Connection } from '../Connection';
 import { sendTransaction } from './transactions';
 import { SetStore, Store } from '@metaplex-foundation/mpl-metaplex';
 
-interface IInitStoreParams {
+/** Parameters for {@link initStore} **/
+export interface InitStoreParams {
   connection: Connection;
+  /** Administrator wallet for the store **/
   wallet: Wallet;
+  /**
+   * - `true`: anyone can list on the store
+   * - `false`: only [whitelisted creators](https://docs.metaplex.com/architecture/deep_dive/metaplex#whitelistedcreator) can list on the store
+   **/
   isPublic?: boolean;
 }
 
-interface IInitStoreResponse {
+export interface InitStoreResponse {
   storeId: PublicKey;
   txId: string;
 }
 
+/**
+ * Initialize a {@link Store} account.
+ * This action will get a {@link Store} program derived account address for the provided wallet and initialize a store with that address, setting the given `wallet` as the admin
+ */
 export const initStore = async ({
   connection,
   wallet,
   isPublic = true,
-}: IInitStoreParams): Promise<IInitStoreResponse> => {
+}: InitStoreParams): Promise<InitStoreResponse> => {
   const storeId = await Store.getPDA(wallet.publicKey);
   const tx = new SetStore(
     { feePayer: wallet.publicKey },

src/actions/initStoreV2.ts

@@ -4,25 +4,35 @@ import { Connection } from '../Connection';
 import { sendTransaction } from './transactions';
 import { SetStoreV2, Store, StoreConfig } from '@metaplex-foundation/mpl-metaplex';
 
-interface IInitStoreV2Params {
+/** Parameters for {@link initStoreV2} **/
+export interface InitStoreV2Params {
   connection: Connection;
+  /** Administrator wallet for the store **/
   wallet: Wallet;
+  /**
+   * - `true`: anyone can list on the store
+   * - `false`: only [whitelisted creators](https://docs.metaplex.com/architecture/deep_dive/metaplex#whitelistedcreator) can list on the store
+   **/
   isPublic?: boolean;
   settingsUri?: string | null;
 }
 
-interface IInitStoreV2Response {
+export interface InitStoreV2Response {
   storeId: PublicKey;
   configId: PublicKey;
   txId: string;
 }
 
+/**
+ * Initialize a {@link Store} account.
+ * This action will get {@link Store} and {@link StoreConfig} program derived account addresses for the provided wallet and initialize a store, setting the given `wallet` as the admin
+ */
 export const initStoreV2 = async ({
   connection,
   wallet,
   settingsUri = null,
   isPublic = true,
-}: IInitStoreV2Params): Promise<IInitStoreV2Response> => {
+}: InitStoreV2Params): Promise<InitStoreV2Response> => {
   const storeId = await Store.getPDA(wallet.publicKey);
   const configId = await StoreConfig.getPDA(storeId);
   const tx = new SetStoreV2(

src/actions/instantSale.ts

@@ -18,14 +18,14 @@ import {
 } from './redeemParticipationBidV3';
 import { cancelBid } from './cancelBid';
 
-interface IInstantSaleParams {
+export interface InstantSaleParams {
   connection: Connection;
   wallet: Wallet;
   auction: PublicKey;
   store: PublicKey;
 }
 
-interface IInstantSaleResponse {
+export interface InstantSaleResponse {
   txIds: TransactionSignature[];
 }
 
@@ -34,7 +34,7 @@ export const instantSale = async ({
   wallet,
   store,
   auction,
-}: IInstantSaleParams): Promise<IInstantSaleResponse> => {
+}: InstantSaleParams): Promise<InstantSaleResponse> => {
   const txIds = [];
   // get data for transactions
   const auctionManagerPDA = await AuctionManager.getPDA(auction);

src/actions/mintEditionFromMaster.ts

@@ -13,14 +13,14 @@ import BN from 'bn.js';
 import { prepareTokenAccountAndMintTxs } from './shared';
 import { sendTransaction } from './transactions';
 
-interface MintEditionFromMasterParams {
+export interface MintEditionFromMasterParams {
   connection: Connection;
   wallet: Wallet;
   masterEditionMint: PublicKey;
   updateAuthority?: PublicKey;
 }
 
-interface MintEditionFromMasterResponse {
+export interface MintEditionFromMasterResponse {
   txId: string;
   mint: PublicKey;
   metadata: PublicKey;

src/actions/mintNFT.ts

@@ -14,10 +14,14 @@ import { sendTransaction } from './transactions';
 import { lookup } from '../utils/metadata';
 import { prepareTokenAccountAndMintTxs } from './shared';
 
+/** Parameters for {@link mintNFT} **/
 export interface MintNFTParams {
   connection: Connection;
+  /** Wallet of the NFT creator and fee payer for the minting action **/
   wallet: Wallet;
+  /** URI for a json file compatible with the {@link MetadataJson} format. Note that the `properties` field has to contain at least one creator and one of the provided creators must have the same public key as the provided {@link wallet} **/
   uri: string;
+  /** Maximum supply of limited edition prints that can be created from the master edition of the minted NFT **/
   maxSupply?: number;
 }