Pack
When using the Pack smart contract, additional top-level functionality is available to use.
When using the Chainlink VRF variation of the Pack contract, use the functionality of the PackVRF Extension instead.
To access the top-level functionality, provide the pack contract type when creating the contract instance:
const contract = await sdk.getContract(
"{{contract_address}}",
"pack", // Provide the "pack" contract type
);
In addition to the methods listed below, the pack contract supports the following extensions:
addPackContents
Add additional tokens to the pool of tokens that can be opened from a pack.
const txResult = await contract.addPackContents(
// ID of the pack you want to add tokens to
"{{pack_id}}",
// Different kinds of tokens to add
{
erc721Rewards: [
{
contractAddress: "{{contract_address}}",
tokenId: "{{token_id}}",
},
],
erc1155Rewards: [
{
contractAddress: "{{contract_address}}",
tokenId: "{{token_id}}",
quantityPerReward: "{{quantity}}",
},
],
erc20Rewards: [
{
contractAddress: "{{contract_address}}",
quantityPerReward: "{{quantity}}",
},
],
},
);
Configuration
packId
The ID of the pack you want to add tokens to.
For example, in your pack contract you may have a common pack with ID 0 and a rare pack with ID 1.
To add more tokens to the common pack, you would pass 0 as the packId.
Must be a string, number, or BigNumber.
rewards
An object containing three (optional) properties:
erc721Rewards: An array of ERC721 tokens to add to the pack. Each item in the array must be an object containing acontractAddressandtokenIdproperty.erc1155Rewards: An array of ERC1155 tokens to add to the pack. Each item in the array must be an object containing acontractAddress,tokenId, andquantityPerRewardproperty.erc20Rewards: An array of ERC20 tokens to add to the pack. Each item in the array must be an object containing acontractAddressandquantityPerRewardproperty.
airdrop
Transfer NFTs from the connected wallet to multiple different wallets at once.
const txResult = await contract.erc1155.airdrop(
// Token ID of the NFT to transfer
"{{token_id}}",
// Array of wallet addresses to transfer to
[
{
address: "{{wallet_address}}", // Wallet address to transfer to
quantity: 1, // Quantity of the NFT to transfer
},
{
address: "{{wallet_address}}", // Wallet address to transfer to
quantity: 2, // Quantity of the NFT to transfer
},
],
);
Configuration
tokenId
The token ID of the NFT to transfer.
Must be a string, number, or BigNumber.
const txResult = await contract.erc1155.airdrop(
"{{token_id}}",
[
// ...
],
);
addresses
An array of objects containing address and quantity properties.
These are the recipients of the airdrop.
const txResult = await contract.erc1155.airdrop("{{token_id}}", [
{
address: "{{wallet_address}}",
quantity: 1,
},
{
address: "{{wallet_address}}",
quantity: 2,
},
]);
balance
Get the quantity of a specific NFT owned by the connected wallet.
const tokenId = 0; // Id of the NFT to check
const balance = await contract.erc1155.balanceOf(tokenId);
Configuration
balanceOf
Get the quantity of a specific NFT owned by a wallet.
// Address of the wallet to check NFT balance
const walletAddress = "{{wallet_address}}";
const tokenId = 0; // Id of the NFT to check
const balance = await contract.erc1155.balanceOf(walletAddress, tokenId);
Configuration
address
The wallet address to check the NFT balance for.
Must be a string.
const balance = await contract.erc1155.balanceOf(
"{{wallet_address}}",
"{{token_id}}",
);
tokenId
The token ID of the NFT to check the balance of.
const balance = await contract.erc1155.balanceOf(
"{{wallet_address}}",
"{{token_id}}",
);
Return Value
A BigNumber representing the quantity of the NFT owned by the wallet.
BigNumber;
create
Mint a new pack NFT, which can be opened to receive rewards, to the connected wallet.
Each pack NFT is an ERC1155 token, which means it can have more than one quantity.
Provide the metadata for the pack NFT itself, and the rewards that can be opened from the pack.
The quantity of packs created is determined by the total number of rewards available, divided by the number of rewards per pack.
For example, if you had 20 total ERC20 rewards + 60 total ERC1155 rewards + 20 total ERC721 rewards,
and you wanted to create packs with 5 rewards each, the result would be the creation of 20 packs (100 total rewards / 5 rewards per pack = 20 packs).
const txResult = await contract.create({
// The metadata for the pack NFT itself
packMetadata: {
name: "My Pack",
description: "This is a new pack",
image: "ipfs://...", // Any IPFS URI, URL, or File object.
// ... Any other metadata you want to include
},
// ERC20 rewards to be included in the pack
erc20Rewards: [
{
contractAddress: "0x...",
quantityPerReward: 5,
totalRewards: 20,
},
],
// ERC721 rewards to be included in the pack
erc721Rewards: [
{
contractAddress: "0x...",
tokenId: 0,
},
],
// ERC1155 rewards to be included in the pack
erc1155Rewards: [
{
contractAddress: "0x...",
tokenId: 0,
quantityPerReward: 1,
totalRewards: 100,
},
],
openStartTime: new Date(), // the date that packs can start to be opened, defaults to now
rewardsPerPack: 1, // the number of rewards in each pack, defaults to 1
});
Configuration
packMetadata
Either a string containing a URL that points to, or an object that contains standard metadata properties.
If you provide an object, (like the example above), the metadata is uploaded and pinned to IPFS for you before the packs are minted. The IPFS URI is then used as the metadata for the pack NFT.
erc20Rewards
An array of ERC20 tokens to include in the pack. Each item in the array must be an object containing a contractAddress, quantityPerReward, and totalRewards property.
erc721Rewards
An array of ERC721 tokens to include in the pack. Each item in the array must be an object containing a contractAddress and tokenId property.
erc1155Rewards
An array of ERC1155 tokens to include in the pack. Each item in the array must be an object containing a contractAddress, tokenId, quantityPerReward, and totalRewards property.
openStartTime
The date that packs can start to be opened. Defaults to new Date() (i.e. now).
Must be of type Date.
rewardsPerPack
The number of rewards in each pack. Defaults to 1.
Must be a number.
createTo
The same as create, but allows you to specify the address that will receive the pack NFT(s), rather than using the connected wallet.
const txResult = await contract.createTo("{{wallet_address}}", {
// The metadata for the pack NFT itself
packMetadata: {
name: "My Pack",
description: "This is a new pack",
image: "ipfs://...",
},
// ERC20 rewards to be included in the pack
erc20Rewards: [
{
contractAddress: "0x...",
quantityPerReward: 5,
totalRewards: 20,
},
],
// ERC721 rewards to be included in the pack
erc721Rewards: [
{
contractAddress: "0x...",
tokenId: 0,
},
],
// ERC1155 rewards to be included in the pack
erc1155Rewards: [
{
contractAddress: "0x...",
tokenId: 0,
quantityPerReward: 1,
totalRewards: 100,
},
],
openStartTime: new Date(), // the date that packs can start to be opened, defaults to now
rewardsPerPack: 1, // the number of rewards in each pack, defaults to 1
});
Configuration
get
Get the metadata of an NFT using it’s token ID.
Metadata is fetched from the uri property of the NFT.
If the metadata is hosted on IPFS, the metadata is fetched and made available as an object.
The object’s image property will be a URL that is available through the thirdweb IPFS gateway.
const nft = await contract.erc1155.get(0);
Configuration
tokenId
The token ID of the NFT to get the metadata for.
Must be a string, number, or BigNumber.
const nft = await contract.erc1155.get(
"{{token_id}}",
);
Return Value
Returns an NFT object containing the following properties:
{
metadata: {
id: string;
uri: string; // The raw URI of the metadata
owner: string;
name?: string | number | undefined;
description?: string | null | undefined;
image?: string | null | undefined; // If the image is hosted on IPFS, the URL is https://gateway.ipfscdn.io/ipfs/<hash>
external_url?: string | null | undefined;
animation_url?: string | null | undefined;
background_color?: string | undefined;
properties?: {
[x: string]: unknown;
} | {
[x: string]: unknown;
}[] | undefined;
};
owner: string;
type: "ERC1155";
supply: number;
quantityOwned?: number;
}
get - Contract Metadata
Get the metadata of a smart contract.
const metadata = await contract.metadata.get();
Configuration
Return Value
While the actual return type is any, you can expect an object containing
properties that follow the
contract level metadata standards, outlined below:
{
name: string; // Name of your smart contract
description?: string; // Short description of your smart contract
image?: string; // Image of your smart contract (any URL, or IPFS URI)
symbol?: string; // Symbol of your smart contract (ticker, e.g. "ETH")
external_link?: string; // Link to view this smart contract on your website
seller_fee_basis_points?: number // The fee you charge on secondary sales, e.g. 100 = 1% seller fee.
fee_recipient?: string; // Wallet address that receives the seller fee
}
get - Owner
Retrieve the wallet address of the owner of the smart contract.
const owner = await contract.owner.get();
Configuration
get - Permissions
Get a list of wallet addresses that are members of a given role.
const members = await contract.roles.get("{{role_name}}");
Configuration
getAll
Get the metadata and current owner of all NFTs in the contract.
By default, returns the first 100 NFTs (in order of token ID). Use queryParams to paginate the results.
const nfts = await contract.erc1155.getAll();
Configuration
queryParams (optional)
Provide an optional object to configure the query. Useful for paginating the results.
const queryParams = {
// The number of NFTs to return
count: 100, // Default is 100
// The index to start from
start: 0, // Default is 0
};
const nfts = await contract.erc1155.getAll(queryParams);
Return Value
Returns an array of NFT objects containing the following properties:
{
metadata: {
id: string;
uri: string; // The raw URI of the metadata
owner: string;
name?: string | number | undefined;
description?: string | null | undefined;
image?: string | null | undefined; // If the image is hosted on IPFS, the URL is https://gateway.ipfscdn.io/ipfs/<hash>
external_url?: string | null | undefined;
animation_url?: string | null | undefined;
background_color?: string | undefined;
properties?: {
[x: string]: unknown;
} | {
[x: string]: unknown;
}[] | undefined;
};
type: "ERC1155";
}[]
getAll - Permissions
Retrieve all of the roles and associated wallets.
const allRoles = await contract.roles.getAll();
Configuration
Return Value
An object containing role names as keys and an array of wallet addresses as the value.
<Record<any, string[]>>
getDefaultRoyaltyInfo
Gets the royalty recipient and BPS (basis points) of the smart contract.
const royaltyInfo = await contract.royalties.getDefaultRoyaltyInfo();
Configuration
Return Value
Returns an object containing the royalty recipient address and BPS (basis points) of the smart contract.
{
seller_fee_basis_points: number;
fee_recipient: string;
}
getOwned
Get all the data associated with the NFTs owned by a specific wallet.
// Address of the wallet to get the NFTs of
const address = "{{wallet_address}}";
const nfts = await contract.erc1155.getOwned(address);
Configuration
address
The address of the wallet to get the NFTs of.
Must be a string.
const nfts = await contract.erc1155.getOwned(
"{{wallet_address}}",
);
Return Value
Returns an array of NFT objects containing the following properties:
{
metadata: {
id: string;
uri: string; // The raw URI of the metadata
owner: string;
name?: string | number | undefined;
description?: string | null | undefined;
image?: string | null | undefined; // If the image is hosted on IPFS, the URL is https://gateway.ipfscdn.io/ipfs/<hash>
external_url?: string | null | undefined;
animation_url?: string | null | undefined;
background_color?: string | undefined;
properties?: {
[x: string]: unknown;
} | {
[x: string]: unknown;
}[] | undefined;
};
type: "ERC1155";
}[]
getPackContents
Get all the tokens that were "wrapped up" in the pack NFTs when they were created.
const contents = await contract.getPackContents("{{pack_id}}");
Configuration
packId
The token ID of the pack to get the contents of.
Must be a string, number, or BigNumber.
Return Value
Returns all the tokens that were included in the rewards when the packs were created.
{
erc20Rewards: {
contractAddress: string;
quantityPerReward: string;
totalRewards: string;
}
[];
erc721Rewards: {
tokenId: string;
contractAddress: string;
}
[];
erc1155Rewards: {
tokenId: string;
contractAddress: string;
quantityPerReward: string;
totalRewards: string;
}
[];
}
getTokenRoyaltyInfo
Gets the royalty recipient and BPS (basis points) of a particular token in the contract.
const royaltyInfo = await contract.royalties.getTokenRoyaltyInfo(
"{{token_id}}",
);
Configuration
grant - Permissions
Make a wallet a member of a given role.
const txResult = await contract.roles.grant(
"{{role_name}}",
"{{wallet_address}}",
);
Configuration
isApproved
Get whether this wallet has approved transfers from the given operator.
This means that the operator can transfer NFTs on behalf of this wallet.
const isApproved = await contract.erc1155.isApproved(
// Address of the wallet to check
"{{wallet_address}}",
// Address of the operator to check
"{{wallet_address}}",
);
Configuration
owner
The wallet address that owns the NFT.
Must be a string.
const isApproved = await contract.erc1155.isApproved(
"{{wallet_address}}",
"{{wallet_address}}",
);
operator
The wallet address of the operator to check (i.e. the wallet that does/does not have approval).
Must be a string.
const isApproved = await contract.erc1155.isApproved(
"{{wallet_address}}",
"{{wallet_address}}",
);
open
Open a pack NFT to receive the rewards inside.
To open a pack, the wallet that initiates this transaction must have sufficient quantity of the pack NFT to open.
const results = await contract.open("{{pack_id}}", "{{amount_to_open}}");
Configuration
revoke - Permissions
Revoke a given role from a wallet.
const txResult = await contract.roles.revoke(
"{{role_name}}",
"{{wallet_address}}",
);
Configuration
set - Contract Metadata
Overwrite the metadata of a contract, an object following the contract level metadata standards.
This operation ignores any existing metadata and replaces it with the new metadata provided.
const txResult = await contract.metadata.set({
name: "My Contract",
description: "My contract description",
});
Configuration
metadata
Provide an object containing the metadata of your smart contract following the contract level metadata standards.
{
name: string; // Name of your smart contract
description?: string; // Short description of your smart contract
image?: string; // Image of your smart contract (any URL, or IPFS URI)
symbol?: string; // Symbol of your smart contract (ticker, e.g. "ETH")
external_link?: string; // Link to view this smart contract on your website
seller_fee_basis_points?: number // The fee you charge on secondary sales, e.g. 100 = 1% seller fee.
fee_recipient?: string; // Wallet address that receives the seller fee
}
set - Owner
Set the owner address of the contract.
const txResult = await contract.owner.set("{{wallet_address}}");
Configuration
owner
The wallet address of the new owner.
Must be a string.
const txResult = await contract.owner.set(
"{{wallet_address}}",
);
setAll - Permissions
Overwrite all roles with new members.
This overwrites all members, INCLUDING YOUR OWN WALLET ADDRESS!
This means you can permanently remove yourself as an admin, which is non-reversible.
Please use this method with caution.
const txResult = await contract.roles.setAll({
admin: ["0x12", "0x123"],
minter: ["0x1234"],
});
Configuration
roles
An object containing role names as keys and an array of wallet addresses as the value.
const txResult = await contract.roles.setAll(
{
admin: ["0x12", "0x123"], // Grant these two wallets the admin role
minter: ["0x1234"], // Grant this wallet the minter role
},
);
setApprovalForAll
Give another address approval (or remove approval) to transfer all of your NFTs from this collection.
Proceed with caution. Only approve addresses you trust.
const txResult = await contract.erc1155.setApprovalForAll(
// Address of the wallet to approve
"{{wallet_address}}",
// Whether to grant approval (true) or remove approval (false)
true,
);
Configuration
operator
The wallet address to approve.
Must be a string.
const txResult = await contract.erc1155.setApprovalForAll(
"{{wallet_address}}",
true,
);
approved
Whether to grant approval (true) or remove approval (false).
Must be a boolean.
const txResult = await contract.erc1155.setApprovalForAll(
"{{wallet_address}}",
true,
);
setDefaultRoyaltyInfo
Set the royalty recipient and fee for the smart contract.
await contract.royalties.setDefaultRoyaltyInfo({
seller_fee_basis_points: 100, // 1% royalty fee
fee_recipient: "0x...", // the fee recipient
});
Configuration
setTokenRoyaltyInfo
Set the royalty recipient and fee for a particular token in the contract.
await contract.royalties.setTokenRoyaltyInfo("{{token_id}}", {
seller_fee_basis_points: 100, // 1% royalty fee
fee_recipient: "0x...", // the fee recipient
});
Configuration
totalCirculatingSupply
Get the total circulating supply of a token in the collection.
Circulating supply considers NFTs that have not been burned.
const totalCirculatingSupply = await contract.erc1155.totalCirculatingSupply(
"{{token_id}}",
);
Configuration
tokenId
The token ID of the NFT to get the total circulating supply of.
Must be a string, number, or BigNumber.
const totalCirculatingSupply = await contract.erc1155.totalCirculatingSupply(
"{{token_id}}",
);
Return Value
Returns a BigNumber representing the total circulating supply of the token.
BigNumber;
totalCount
Get the total number of unique NFTs in the collection.
const totalCount = await contract.erc1155.totalCount();
Return Value
Returns a BigNumber representing the total number of unique NFTs in the collection.
BigNumber;
transfer
Transfer an NFT from the connected wallet to another wallet.
// Address of the wallet you want to send the NFT to
const toAddress = "{{wallet_address}}";
const tokenId = "0"; // The token ID of the NFT you want to send
const amount = 3; // How many copies of the NFTs to transfer
await contract.erc1155.transfer(toAddress, tokenId, amount);
Configuration
to
The wallet address to send the NFT to.
Must be a string.
await contract.erc1155.transfer(
"{{wallet_address}}",
"{{token_id}}",
"{{amount}}",
);
tokenId
The token ID of the NFT to transfer.
Must be a string, number, or BigNumber.
await contract.erc1155.transfer(
"{{wallet_address}}",
"{{token_id}}",
"{{amount}}",
);
amount
The quantity of the NFT to transfer.
Must be a string, number, or BigNumber.
await contract.erc1155.transfer(
"{{wallet_address}}",
"{{token_id}}",
"{{amount}}",
);
totalSupply
Returns the total supply of a token in the collection, including burned tokens.
const totalSupply = await contract.erc1155.totalSupply("{{token_id}}");
Configuration
update - Contract Metadata
Update the metadata of your smart contract.
const txResult = await contract.metadata.update({
name: "My Contract",
description: "My contract description",
});
Configuration
metadata
Provide an object containing the metadata of your smart contract following the contract level metadata standards.
New properties will be added, and existing properties will be overwritten. If you do not provide a new value for a previously set property, it will remain unchanged.
Below are the properties you can define on your smart contract.
{
name: string; // Name of your smart contract
description?: string; // Short description of your smart contract
image?: string; // Image of your smart contract (any URL, or IPFS URI)
symbol?: string; // Symbol of your smart contract (ticker, e.g. "ETH")
external_link?: string; // Link to view this smart contract on your website
seller_fee_basis_points?: number // The fee you charge on secondary sales, e.g. 100 = 1% seller fee.
fee_recipient?: string; // Wallet address that receives the seller fee
}
verify - Permissions
Check to see if a wallet has a set of roles.
Throws an error if the wallet does not have any of the given roles.
const verifyRole = await contract.roles.verify(
["admin", "minter"],
"{{wallet_address}}",
);