From 2f3654cab7170947ff37ad4a8137bb2c2c252f77 Mon Sep 17 00:00:00 2001 From: Danny Povolotski Date: Sat, 22 Jan 2022 20:06:28 +0300 Subject: [PATCH 01/12] docs: initial documentation --- package.json | 1 + src/actions/burnToken.ts | 8 ++++---- src/actions/cancelBid.ts | 8 +++++--- src/actions/claimBid.ts | 6 +++--- src/actions/createMasterEdition.ts | 19 +++++++++++++++---- src/actions/createMetadata.ts | 17 +++++++++++++++-- src/actions/initStore.ts | 6 +++--- src/actions/initStoreV2.ts | 6 +++--- src/actions/instantSale.ts | 6 +++--- src/actions/mintEditionFromMaster.ts | 4 ++-- src/actions/mintNFT.ts | 4 ++++ src/actions/placeBid.ts | 6 +++--- src/actions/redeemFullRightsTransferBid.ts | 10 +++++----- src/actions/redeemParticipationBidV3.ts | 6 +++--- src/actions/redeemPrintingV2Bid.ts | 10 +++++----- src/actions/sendToken.ts | 6 +++--- src/actions/signMetadata.ts | 2 +- src/actions/transactions.ts | 2 +- src/actions/updateMetadata.ts | 17 +++++++++++------ src/providers/conversion/Coingecko.ts | 14 +++++++++++++- typedoc.json | 2 +- 21 files changed, 104 insertions(+), 56 deletions(-) diff --git a/package.json b/package.json index e324742..ae5617b 100644 --- a/package.json +++ b/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", diff --git a/src/actions/burnToken.ts b/src/actions/burnToken.ts index 9b05c86..99b09d5 100644 --- a/src/actions/burnToken.ts +++ b/src/actions/burnToken.ts @@ -5,18 +5,18 @@ import { sendTransaction } from './transactions'; import { Transaction } from '@metaplex-foundation/mpl-core'; import { Token, TOKEN_PROGRAM_ID, u64 } from '@solana/spl-token'; -interface IBurnTokenParams { +export interface BurnTokenParams { connection: Connection; wallet: Wallet; token: PublicKey; mint: PublicKey; amount: number | u64; 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; } @@ -28,7 +28,7 @@ export const burnToken = async ({ amount, owner, close = true, -}: IBurnTokenParams): Promise => { +}: BurnTokenParams): Promise => { const tx = new Transaction({ feePayer: wallet.publicKey }).add( Token.createBurnInstruction( TOKEN_PROGRAM_ID, diff --git a/src/actions/cancelBid.ts b/src/actions/cancelBid.ts index b9b8f1d..12ad3e3 100644 --- a/src/actions/cancelBid.ts +++ b/src/actions/cancelBid.ts @@ -14,15 +14,17 @@ import { AuctionManager } from '@metaplex-foundation/mpl-metaplex'; import { CreateTokenAccount } from '../transactions'; import { Transaction } from '@metaplex-foundation/mpl-core'; -interface ICancelBidParams { +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; bidderPotToken: PublicKey; destAccount?: PublicKey; } -interface ICancelBidResponse { +export interface CancelBidResponse { txId: string; } @@ -32,7 +34,7 @@ export const cancelBid = async ({ auction, bidderPotToken, destAccount, -}: ICancelBidParams): Promise => { +}: CancelBidParams): Promise => { const bidder = wallet.publicKey; const auctionManager = await AuctionManager.getPDA(auction); const manager = await AuctionManager.load(connection, auctionManager); diff --git a/src/actions/claimBid.ts b/src/actions/claimBid.ts index 44d6de9..4dc3933 100644 --- a/src/actions/claimBid.ts +++ b/src/actions/claimBid.ts @@ -6,7 +6,7 @@ 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 { +export interface ClaimBidParams { connection: Connection; wallet: Wallet; auction: PublicKey; @@ -14,7 +14,7 @@ interface IClaimBidParams { bidderPotToken: PublicKey; } -interface IClaimBidResponse { +export interface ClaimBidResponse { txId: string; } @@ -24,7 +24,7 @@ export const claimBid = async ({ store, auction, bidderPotToken, -}: IClaimBidParams): Promise => { +}: ClaimBidParams): Promise => { // get data for transactions const bidder = wallet.publicKey; const auctionManager = await AuctionManager.getPDA(auction); diff --git a/src/actions/createMasterEdition.ts b/src/actions/createMasterEdition.ts index 15bc956..67782e2 100644 --- a/src/actions/createMasterEdition.ts +++ b/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, diff --git a/src/actions/createMetadata.ts b/src/actions/createMetadata.ts index 50e665d..834d078 100644 --- a/src/actions/createMetadata.ts +++ b/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 => { diff --git a/src/actions/initStore.ts b/src/actions/initStore.ts index d0dc9c3..649b9ff 100644 --- a/src/actions/initStore.ts +++ b/src/actions/initStore.ts @@ -4,13 +4,13 @@ import { Connection } from '../Connection'; import { sendTransaction } from './transactions'; import { SetStore, Store } from '@metaplex-foundation/mpl-metaplex'; -interface IInitStoreParams { +export interface InitStoreParams { connection: Connection; wallet: Wallet; isPublic?: boolean; } -interface IInitStoreResponse { +export interface InitStoreResponse { storeId: PublicKey; txId: string; } @@ -19,7 +19,7 @@ export const initStore = async ({ connection, wallet, isPublic = true, -}: IInitStoreParams): Promise => { +}: InitStoreParams): Promise => { const storeId = await Store.getPDA(wallet.publicKey); const tx = new SetStore( { feePayer: wallet.publicKey }, diff --git a/src/actions/initStoreV2.ts b/src/actions/initStoreV2.ts index 5d274a1..8429acb 100644 --- a/src/actions/initStoreV2.ts +++ b/src/actions/initStoreV2.ts @@ -4,14 +4,14 @@ import { Connection } from '../Connection'; import { sendTransaction } from './transactions'; import { SetStoreV2, Store, StoreConfig } from '@metaplex-foundation/mpl-metaplex'; -interface IInitStoreV2Params { +export interface InitStoreV2Params { connection: Connection; wallet: Wallet; isPublic?: boolean; settingsUri?: string | null; } -interface IInitStoreV2Response { +export interface InitStoreV2Response { storeId: PublicKey; configId: PublicKey; txId: string; @@ -22,7 +22,7 @@ export const initStoreV2 = async ({ wallet, settingsUri = null, isPublic = true, -}: IInitStoreV2Params): Promise => { +}: InitStoreV2Params): Promise => { const storeId = await Store.getPDA(wallet.publicKey); const configId = await StoreConfig.getPDA(storeId); const tx = new SetStoreV2( diff --git a/src/actions/instantSale.ts b/src/actions/instantSale.ts index b9c9cd7..d56c64a 100644 --- a/src/actions/instantSale.ts +++ b/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 => { +}: InstantSaleParams): Promise => { const txIds = []; // get data for transactions const auctionManagerPDA = await AuctionManager.getPDA(auction); diff --git a/src/actions/mintEditionFromMaster.ts b/src/actions/mintEditionFromMaster.ts index 7e6af94..904ba25 100644 --- a/src/actions/mintEditionFromMaster.ts +++ b/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; diff --git a/src/actions/mintNFT.ts b/src/actions/mintNFT.ts index aad0b30..c47fe09 100644 --- a/src/actions/mintNFT.ts +++ b/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; } diff --git a/src/actions/placeBid.ts b/src/actions/placeBid.ts index 945ae00..cebbf30 100644 --- a/src/actions/placeBid.ts +++ b/src/actions/placeBid.ts @@ -16,7 +16,7 @@ import { getCancelBidTransactions } from './cancelBid'; import { CreateTokenAccount } from '../transactions'; import { createApproveTxs, createWrappedAccountTxs } from './shared'; -interface IPlaceBidParams { +export interface PlaceBidParams { connection: Connection; wallet: Wallet; auction: PublicKey; @@ -26,7 +26,7 @@ interface IPlaceBidParams { commitment?: Commitment; } -interface IPlaceBidResponse { +export interface PlaceBidResponse { txId: TransactionSignature; bidderPotToken: PublicKey; bidderMeta: PublicKey; @@ -38,7 +38,7 @@ export const placeBid = async ({ amount, auction, bidderPotToken, -}: IPlaceBidParams): Promise => { +}: PlaceBidParams): Promise => { // get data for transactions const bidder = wallet.publicKey; const accountRentExempt = await connection.getMinimumBalanceForRentExemption(AccountLayout.span); diff --git a/src/actions/redeemFullRightsTransferBid.ts b/src/actions/redeemFullRightsTransferBid.ts index 59cd86e..2094ad2 100644 --- a/src/actions/redeemFullRightsTransferBid.ts +++ b/src/actions/redeemFullRightsTransferBid.ts @@ -18,14 +18,14 @@ import { UpdatePrimarySaleHappenedViaToken, } from '@metaplex-foundation/mpl-token-metadata'; -interface IRedeemBidParams { +export interface RedeemFullRightsTransferBidParams { connection: Connection; wallet: Wallet; auction: PublicKey; store: PublicKey; } -interface IRedeemBidResponse { +export interface RedeemFullRightsTransferBidResponse { txId: string; } @@ -34,7 +34,7 @@ export const redeemFullRightsTransferBid = async ({ wallet, store, auction, -}: IRedeemBidParams): Promise => { +}: RedeemFullRightsTransferBidParams): Promise => { // get data for transactions const bidder = wallet.publicKey; const accountRentExempt = await connection.getMinimumBalanceForRentExemption(AccountLayout.span); @@ -86,7 +86,7 @@ export const redeemFullRightsTransferBid = async ({ return { txId }; }; -interface IRedeemBidTransactionsParams { +interface RedeemFRTBidTransactionsParams { bidder: PublicKey; accountRentExempt: number; bidderPotToken?: PublicKey; @@ -123,7 +123,7 @@ export const getRedeemFRTBidTransactions = async ({ safetyDepositConfig, transferAuthority, metadata, -}: IRedeemBidTransactionsParams) => { +}: RedeemFRTBidTransactionsParams) => { const txBatch = new TransactionsBatch({ transactions: [] }); // create a new account for redeeming diff --git a/src/actions/redeemParticipationBidV3.ts b/src/actions/redeemParticipationBidV3.ts index f77dd29..ff7acc5 100644 --- a/src/actions/redeemParticipationBidV3.ts +++ b/src/actions/redeemParticipationBidV3.ts @@ -31,14 +31,14 @@ import { UpdatePrimarySaleHappenedViaToken, } from '@metaplex-foundation/mpl-token-metadata'; -interface IRedeemParticipationBidV3Params { +export interface RedeemParticipationBidV3Params { connection: Connection; wallet: Wallet; auction: PublicKey; store: PublicKey; } -interface IRedeemParticipationBidV3Response { +export interface RedeemParticipationBidV3Response { txIds: TransactionSignature[]; } @@ -47,7 +47,7 @@ export const redeemParticipationBidV3 = async ({ wallet, store, auction, -}: IRedeemParticipationBidV3Params): Promise => { +}: RedeemParticipationBidV3Params): Promise => { const txInitBatch = new TransactionsBatch({ transactions: [] }); const txMainBatch = new TransactionsBatch({ transactions: [] }); diff --git a/src/actions/redeemPrintingV2Bid.ts b/src/actions/redeemPrintingV2Bid.ts index e0e2339..d9f3d02 100644 --- a/src/actions/redeemPrintingV2Bid.ts +++ b/src/actions/redeemPrintingV2Bid.ts @@ -22,18 +22,18 @@ import { RedeemPrintingV2Bid } from '@metaplex-foundation/mpl-metaplex'; import { prepareTokenAccountAndMintTxs } from './shared'; import { getBidRedemptionPDA } from './redeemFullRightsTransferBid'; -interface IRedeemBidParams { +export interface RedeemBidParams { connection: Connection; wallet: Wallet; auction: PublicKey; store: PublicKey; } -interface IRedeemBidResponse { +export interface RedeemBidResponse { txId: string; } -interface IRedeemBidTransactionsParams { +export interface RedeemBidTransactionsParams { bidder: PublicKey; bidderPotToken?: PublicKey; bidderMeta: PublicKey; @@ -63,7 +63,7 @@ export const redeemPrintingV2Bid = async ({ wallet, store, auction, -}: IRedeemBidParams): Promise => { +}: RedeemBidParams): Promise => { const bidder = wallet.publicKey; const { data: { bidState }, @@ -186,7 +186,7 @@ export const getRedeemPrintingV2BidTransactions = async ({ winIndex, editionOffset, -}: IRedeemBidTransactionsParams) => { +}: RedeemBidTransactionsParams) => { const txBatch = new TransactionsBatch({ transactions: [] }); const redeemPrintingV2BidTx = new RedeemPrintingV2Bid( diff --git a/src/actions/sendToken.ts b/src/actions/sendToken.ts index 72db68f..7c9141a 100644 --- a/src/actions/sendToken.ts +++ b/src/actions/sendToken.ts @@ -6,7 +6,7 @@ import { sendTransaction } from './transactions'; import { Account, Transaction } from '@metaplex-foundation/mpl-core'; import { CreateAssociatedTokenAccount } from '../transactions/CreateAssociatedTokenAccount'; -interface ISendTokenParams { +export interface SendTokenParams { connection: Connection; wallet: Wallet; // token account address @@ -17,7 +17,7 @@ interface ISendTokenParams { amount: number | u64; } -interface ISendTokenResponse { +export interface SendTokenResponse { txId: string; } @@ -28,7 +28,7 @@ export const sendToken = async ({ destination, mint, amount, -}: ISendTokenParams): Promise => { +}: SendTokenParams): Promise => { const txs = []; const destAta = await Token.getAssociatedTokenAddress( ASSOCIATED_TOKEN_PROGRAM_ID, diff --git a/src/actions/signMetadata.ts b/src/actions/signMetadata.ts index 24b378c..da011a1 100644 --- a/src/actions/signMetadata.ts +++ b/src/actions/signMetadata.ts @@ -3,7 +3,7 @@ import { Wallet } from '../wallet'; import { Metadata, SignMetadata } from '@metaplex-foundation/mpl-token-metadata'; import { sendTransaction } from './transactions'; -interface SignMetadataParams { +export interface SignMetadataParams { connection: Connection; wallet: Wallet; editionMint: PublicKey; diff --git a/src/actions/transactions.ts b/src/actions/transactions.ts index e67a764..b38a553 100644 --- a/src/actions/transactions.ts +++ b/src/actions/transactions.ts @@ -3,7 +3,7 @@ import { Wallet } from '../wallet'; import { Connection } from '../Connection'; import { Transaction } from '@metaplex-foundation/mpl-core'; -interface ISendTransactionParams { +export interface ISendTransactionParams { connection: Connection; wallet: Wallet; txs: Transaction[]; diff --git a/src/actions/updateMetadata.ts b/src/actions/updateMetadata.ts index 832509c..8d352f7 100644 --- a/src/actions/updateMetadata.ts +++ b/src/actions/updateMetadata.ts @@ -7,20 +7,25 @@ import { } from '@metaplex-foundation/mpl-token-metadata'; import { sendTransaction } from './transactions'; -interface UpdateMetadataParams { +/** Parameters for {@link updateMetadata} **/ +export interface UpdateMetadataParams { connection: Connection; + /** Must be the wallet of the current `updateAuthority` **/ wallet: Wallet; + /** Mint address for the NFT token **/ editionMint: PublicKey; + /** An optional new {@link MetadataDataData} object to replace the current data. This will completely overwrite the data so all fields must be set explicitly. **/ newMetadataData?: MetadataDataData; newUpdateAuthority?: PublicKey; + /** This parameter can only be set to true once after which it can't be reverted to false **/ primarySaleHappened?: boolean; } -/* - * Can be used to update any of the below 3: - * 1) data inside metadata, but only if it's mutable (which is only possible for MasterEditions) - * 2) updateAuthority - * 3) whether primary sale has happened (can only be set true, never back false) +/** + * Can be used to update any of the following parameters: + * 1. Data inside {@link Metadata} as long as it remains mutable (which is only possible for a {@link MasterEdition}) + * 2. updateAuthority + * 3. Whether the primary sale has happened (can only be set to true once after which it can't be reverted to false) */ export const updateMetadata = async ( { diff --git a/src/providers/conversion/Coingecko.ts b/src/providers/conversion/Coingecko.ts index 5df4022..0239fe5 100644 --- a/src/providers/conversion/Coingecko.ts +++ b/src/providers/conversion/Coingecko.ts @@ -1,8 +1,15 @@ import { ConversionRateProvider, Currency, ConversionRatePair } from './ConversionRateProvider'; import axios from 'axios'; +/** + * Provides currency rate converstion via CoinGecko API. + */ export class Coingecko implements ConversionRateProvider { - // this method translates currency strings to the format that coingecko requires + /** + * Translates currency strings from the internal Currency enum to the format that Coingecko requires + * @param currency + * @returns The provided currency in a format that Coingecko API recognizes. For instance, {@link Currency.AR} becomes 'arweave' + */ static translateCurrency(currency: Currency): string { switch (currency) { case Currency.AR: @@ -18,6 +25,11 @@ export class Coingecko implements ConversionRateProvider { } } + /** + * Provides conversion rates for each `from` currency into all the provided `to` currencies + * @param from + * @param to + */ async getRate(from: Currency | Currency[], to: Currency | Currency[]) { const fromArray = typeof from === 'string' ? [from] : from; const toArray = typeof to === 'string' ? [to] : to; diff --git a/typedoc.json b/typedoc.json index 920767e..4ac30b6 100644 --- a/typedoc.json +++ b/typedoc.json @@ -5,4 +5,4 @@ "excludeInternal": true, "excludePrivate": true, "out": "./docs" -} \ No newline at end of file +} From 1a585fee8fe671011bb6d6737139906edf62e01a Mon Sep 17 00:00:00 2001 From: Danny Povolotski Date: Sat, 22 Jan 2022 21:05:48 +0300 Subject: [PATCH 02/12] docs: sendToken --- src/actions/sendToken.ts | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/src/actions/sendToken.ts b/src/actions/sendToken.ts index 7c9141a..9875787 100644 --- a/src/actions/sendToken.ts +++ b/src/actions/sendToken.ts @@ -6,14 +6,18 @@ import { sendTransaction } from './transactions'; import { Account, Transaction } from '@metaplex-foundation/mpl-core'; import { CreateAssociatedTokenAccount } from '../transactions/CreateAssociatedTokenAccount'; +/** Parameters for {@link sendToken} **/ export interface SendTokenParams { connection: Connection; + /** Source wallet address **/ wallet: Wallet; - // token account address + /** Source wallet's associated token account address **/ source: PublicKey; - // destination wallet address + /** Destination wallet address **/ destination: PublicKey; + /** Mint address of the tokento transfer **/ mint: PublicKey; + /** Amount of tokens to transfer. 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 send 1 token with a 0 decimal mint you would provide `0` as the amount, but for a token mint with 6 decimals you would provide `1000000` as the amount to transfer one whole token **/ amount: number | u64; } @@ -21,6 +25,16 @@ export interface SendTokenResponse { txId: string; } +/** + * Send a token to another account. + * + * This action will do the following: + * 1. Check if the destination account has an associated token account for the SPL token at hand + * 2. If the associated token account doesn't exist, it will be created + * 3. The token will be transferred to the associated token account + * + * Please take into account that creating an account will [automatically allocate lamports for rent exemption](https://docs.solana.com/implemented-proposals/rent) which will make it a very expensive instruction to run in bulk + */ export const sendToken = async ({ connection, wallet, From 2a504ecb8fa82d4b0d7e306917c6ec6b344d6dee Mon Sep 17 00:00:00 2001 From: Danny Povolotski Date: Sat, 22 Jan 2022 21:15:43 +0300 Subject: [PATCH 03/12] docs: signMetadata --- src/actions/signMetadata.ts | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/actions/signMetadata.ts b/src/actions/signMetadata.ts index da011a1..0779963 100644 --- a/src/actions/signMetadata.ts +++ b/src/actions/signMetadata.ts @@ -3,13 +3,23 @@ import { Wallet } from '../wallet'; import { Metadata, SignMetadata } from '@metaplex-foundation/mpl-token-metadata'; import { sendTransaction } from './transactions'; +/** + * Parameters for {@link signMetadata} + */ export interface SignMetadataParams { connection: Connection; + /** Will be used as both the fee payer and {@link signer} if no separate {@link signer} was otherwise specified. If used as a signer, the wallet address must be included in the `creators` array. **/ wallet: Wallet; + /** Mint address for the token associated with the {@link Metadata} account **/ editionMint: PublicKey; + /** An optional signer. If specified, the signer address must be included in the `creators` array on the {@link Metadata} account data **/ signer?: Keypair; } +/** + * Sign a MetaData account that has the provided wallet as an unverified creator so that it is now verified. + * @return This action returns the resulting transaction id once it has been executed + */ export const signMetadata = async ( { connection, wallet, editionMint, signer } = {} as SignMetadataParams, ): Promise => { From ca683acad9a2b9e538fbd0b94fed9890ff9f7868 Mon Sep 17 00:00:00 2001 From: Danny Povolotski Date: Sat, 22 Jan 2022 21:42:07 +0300 Subject: [PATCH 04/12] docs: transactions --- src/actions/transactions.ts | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/src/actions/transactions.ts b/src/actions/transactions.ts index b38a553..0d561f7 100644 --- a/src/actions/transactions.ts +++ b/src/actions/transactions.ts @@ -3,7 +3,8 @@ import { Wallet } from '../wallet'; import { Connection } from '../Connection'; import { Transaction } from '@metaplex-foundation/mpl-core'; -export interface ISendTransactionParams { +/** Parameters for {@link sendTransaction} **/ +export interface SendTransactionParams { connection: Connection; wallet: Wallet; txs: Transaction[]; @@ -11,13 +12,17 @@ export interface ISendTransactionParams { options?: SendOptions; } +/** + * Sign and send transactions for validation + * @return This action returns the resulting transaction id once it has been executed + */ export const sendTransaction = async ({ connection, wallet, txs, signers = [], options, -}: ISendTransactionParams): Promise => { +}: SendTransactionParams): Promise => { let tx = Transaction.fromCombined(txs, { feePayer: wallet.publicKey }); tx.recentBlockhash = (await connection.getRecentBlockhash()).blockhash; From 1ff0d0ba50e29217db281b107a431c877ab43664 Mon Sep 17 00:00:00 2001 From: Danny Povolotski Date: Sun, 23 Jan 2022 00:09:27 +0300 Subject: [PATCH 05/12] docs: initStore --- src/actions/initStore.ts | 11 +++++++++++ src/actions/initStoreV2.ts | 10 ++++++++++ 2 files changed, 21 insertions(+) diff --git a/src/actions/initStore.ts b/src/actions/initStore.ts index 649b9ff..b76baf2 100644 --- a/src/actions/initStore.ts +++ b/src/actions/initStore.ts @@ -4,9 +4,15 @@ import { Connection } from '../Connection'; import { sendTransaction } from './transactions'; import { SetStore, Store } from '@metaplex-foundation/mpl-metaplex'; +/** 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 can list on the store + **/ isPublic?: boolean; } @@ -15,6 +21,11 @@ export interface InitStoreResponse { 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 + * @deprecated This action is deprecated, please use {@link initStoreV2} instead + */ export const initStore = async ({ connection, wallet, diff --git a/src/actions/initStoreV2.ts b/src/actions/initStoreV2.ts index 8429acb..2223cca 100644 --- a/src/actions/initStoreV2.ts +++ b/src/actions/initStoreV2.ts @@ -4,9 +4,15 @@ import { Connection } from '../Connection'; import { sendTransaction } from './transactions'; import { SetStoreV2, Store, StoreConfig } from '@metaplex-foundation/mpl-metaplex'; +/** 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 can list on the store + **/ isPublic?: boolean; settingsUri?: string | null; } @@ -17,6 +23,10 @@ export interface InitStoreV2Response { 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, From 19a32f0dd3dc1e3d7e7d03f7dc865e4a00999038 Mon Sep 17 00:00:00 2001 From: Danny Povolotski Date: Sun, 23 Jan 2022 00:35:40 +0300 Subject: [PATCH 06/12] docs: cancelBid --- src/actions/cancelBid.ts | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/src/actions/cancelBid.ts b/src/actions/cancelBid.ts index 12ad3e3..4d2ff72 100644 --- a/src/actions/cancelBid.ts +++ b/src/actions/cancelBid.ts @@ -14,13 +14,18 @@ import { AuctionManager } from '@metaplex-foundation/mpl-metaplex'; import { CreateTokenAccount } from '../transactions'; import { Transaction } from '@metaplex-foundation/mpl-core'; +/** + * 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; } @@ -28,6 +33,9 @@ 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, @@ -72,7 +80,7 @@ export const cancelBid = async ({ return { txId }; }; -interface ICancelBidTransactionsParams { +interface CancelBidTransactionsParams { destAccount?: PublicKey; bidder: PublicKey; accountRentExempt: number; @@ -96,7 +104,7 @@ export const getCancelBidTransactions = async ({ auctionExtended, auctionTokenMint, vault, -}: ICancelBidTransactionsParams): Promise => { +}: CancelBidTransactionsParams): Promise => { const txBatch = new TransactionsBatch({ transactions: [] }); if (!destAccount) { const account = Keypair.generate(); From 566d31b6de40d7d04633e78530e4fdc51c8f7988 Mon Sep 17 00:00:00 2001 From: Danny Povolotski Date: Sun, 23 Jan 2022 02:00:03 +0300 Subject: [PATCH 07/12] docs: claimBid --- src/actions/claimBid.ts | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/actions/claimBid.ts b/src/actions/claimBid.ts index 4dc3933..6e97450 100644 --- a/src/actions/claimBid.ts +++ b/src/actions/claimBid.ts @@ -6,11 +6,18 @@ import { Auction, AuctionExtended, BidderPot } from '@metaplex-foundation/mpl-au import { TransactionsBatch } from '../utils/transactions-batch'; import { AuctionManager, ClaimBid } from '@metaplex-foundation/mpl-metaplex'; +/** + * 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; } @@ -18,6 +25,9 @@ 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, From 9e4c543a1808d53f83537fd80c57ee85567435f8 Mon Sep 17 00:00:00 2001 From: Danny Povolotski Date: Tue, 25 Jan 2022 21:39:24 +0300 Subject: [PATCH 08/12] docs: placeBid --- src/actions/placeBid.ts | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/src/actions/placeBid.ts b/src/actions/placeBid.ts index cebbf30..1f90ca7 100644 --- a/src/actions/placeBid.ts +++ b/src/actions/placeBid.ts @@ -16,12 +16,18 @@ import { getCancelBidTransactions } from './cancelBid'; import { CreateTokenAccount } from '../transactions'; import { createApproveTxs, createWrappedAccountTxs } from './shared'; +/** + * Parameters for {@link placeBid} + */ export interface PlaceBidParams { connection: Connection; + /** The wallet from which tokens will be taken and transferred to the {@link bidderPotToken} account **/ wallet: Wallet; + /** The {@link Auction} program account address for the bid **/ auction: PublicKey; + /** Associated token account for the bidder pot **/ bidderPotToken?: PublicKey; - // amount in lamports + /** Amount of tokens (accounting for decimals) or lamports to bid. 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 send 1 token with a 0 decimal mint you would provide `0` as the amount, but for a token mint with 6 decimals you would provide `1000000` as the amount to transfer one whole token **/ amount: BN; commitment?: Commitment; } @@ -32,6 +38,9 @@ export interface PlaceBidResponse { bidderMeta: PublicKey; } +/** + * Place a bit by taking it from the provided wallet and placing it in the bidder pot account. + */ export const placeBid = async ({ connection, wallet, From 0cf971f5802dbe9f65de4e86d84ff857b0c1121d Mon Sep 17 00:00:00 2001 From: Danny Povolotski Date: Wed, 26 Jan 2022 02:05:32 +0300 Subject: [PATCH 09/12] Update src/actions/placeBid.ts Co-authored-by: Aaron Heckmann --- src/actions/placeBid.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/actions/placeBid.ts b/src/actions/placeBid.ts index 1f90ca7..211e3ef 100644 --- a/src/actions/placeBid.ts +++ b/src/actions/placeBid.ts @@ -39,7 +39,7 @@ export interface PlaceBidResponse { } /** - * Place a bit by taking it from the provided wallet and placing it in the bidder pot account. + * Place a bid by taking it from the provided wallet and placing it in the bidder pot account. */ export const placeBid = async ({ connection, From dee169cf137bb739eda03613b4051ff8148d7028 Mon Sep 17 00:00:00 2001 From: Danny Povolotski Date: Wed, 26 Jan 2022 02:15:55 +0300 Subject: [PATCH 10/12] feedback from aaron implemented --- src/actions/initStore.ts | 1 - src/actions/initStoreV2.ts | 2 +- src/actions/placeBid.ts | 2 +- src/actions/sendToken.ts | 2 +- 4 files changed, 3 insertions(+), 4 deletions(-) diff --git a/src/actions/initStore.ts b/src/actions/initStore.ts index b76baf2..5e8269d 100644 --- a/src/actions/initStore.ts +++ b/src/actions/initStore.ts @@ -24,7 +24,6 @@ export interface InitStoreResponse { /** * 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 - * @deprecated This action is deprecated, please use {@link initStoreV2} instead */ export const initStore = async ({ connection, diff --git a/src/actions/initStoreV2.ts b/src/actions/initStoreV2.ts index 2223cca..92039f1 100644 --- a/src/actions/initStoreV2.ts +++ b/src/actions/initStoreV2.ts @@ -11,7 +11,7 @@ export interface InitStoreV2Params { wallet: Wallet; /** * - `true`: anyone can list on the store - * - `false`: only whitelisted creators 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; diff --git a/src/actions/placeBid.ts b/src/actions/placeBid.ts index 211e3ef..5bb0400 100644 --- a/src/actions/placeBid.ts +++ b/src/actions/placeBid.ts @@ -27,7 +27,7 @@ export interface PlaceBidParams { auction: PublicKey; /** Associated token account for the bidder pot **/ bidderPotToken?: PublicKey; - /** Amount of tokens (accounting for decimals) or lamports to bid. 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 send 1 token with a 0 decimal mint you would provide `0` as the amount, but for a token mint with 6 decimals you would provide `1000000` as the amount to transfer one whole token **/ + /** Amount of tokens (accounting for decimals) or lamports to bid. 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 send 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 transfer one whole token **/ amount: BN; commitment?: Commitment; } diff --git a/src/actions/sendToken.ts b/src/actions/sendToken.ts index 9875787..1153b42 100644 --- a/src/actions/sendToken.ts +++ b/src/actions/sendToken.ts @@ -17,7 +17,7 @@ export interface SendTokenParams { destination: PublicKey; /** Mint address of the tokento transfer **/ mint: PublicKey; - /** Amount of tokens to transfer. 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 send 1 token with a 0 decimal mint you would provide `0` as the amount, but for a token mint with 6 decimals you would provide `1000000` as the amount to transfer one whole token **/ + /** Amount of tokens to transfer. 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 send 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 transfer one whole token **/ amount: number | u64; } From 88b895cef62d5801e6fb2a65058ba940d2dec231 Mon Sep 17 00:00:00 2001 From: Danny Povolotski Date: Wed, 26 Jan 2022 02:18:54 +0300 Subject: [PATCH 11/12] docs: another whitelisted creator link --- src/actions/initStore.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/actions/initStore.ts b/src/actions/initStore.ts index 5e8269d..f862dd8 100644 --- a/src/actions/initStore.ts +++ b/src/actions/initStore.ts @@ -11,7 +11,7 @@ export interface InitStoreParams { wallet: Wallet; /** * - `true`: anyone can list on the store - * - `false`: only whitelisted creators 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; } From 97981a6fdf4af61a9471169a7af5bca8563d52e9 Mon Sep 17 00:00:00 2001 From: Danny Povolotski Date: Fri, 28 Jan 2022 14:04:27 +0300 Subject: [PATCH 12/12] docs: burnToken --- src/actions/burnToken.ts | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/src/actions/burnToken.ts b/src/actions/burnToken.ts index 99b09d5..b07f3b8 100644 --- a/src/actions/burnToken.ts +++ b/src/actions/burnToken.ts @@ -5,12 +5,18 @@ import { sendTransaction } from './transactions'; import { Transaction } from '@metaplex-foundation/mpl-core'; import { Token, TOKEN_PROGRAM_ID, u64 } from '@solana/spl-token'; +/** 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; /** Set to `true` if you wish to close the token account after burning the token **/ close?: boolean; @@ -20,10 +26,13 @@ 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, @@ -33,7 +42,7 @@ export const burnToken = async ({ 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, [],