Token Drop
When using the Token Drop smart contract, there is no need to provide a contract type argument, as the functionality of the smart contract is all available through the extensions interface.
The extensions that the Token Drop contract supports are listed below.
- ERC20
- ERC20Burnable
- ERC20ClaimPhases
- ERC20Permit
- PlatformFee
- PrimarySale
- Permissions
- ContractMetadata
- Gasless
allowance
Get the allowance of another wallet address over the connected wallet's funds.
"Allowance" refers to the number of tokens that another wallet is allowed to spend on behalf of the connected wallet.
// Address of the wallet to check token allowance
const spenderAddress = "{{wallet_address}}";
const allowance = await contract.erc20.allowance(spenderAddress);
Configuration
spender
The address of the wallet to check the allowance of.
Must be a string
.
const allowance = await contract.erc20.allowance(
"{{wallet_address}}",
);
Return Value
A CurrencyValue
object is returned with the allowance available in the value
property.
{
value: BigNumber;
symbol: string;
name: string;
decimals: number;
displayValue: string;
}
allowanceOf
The same as allowance
, but allows you to specify the owner wallet to check, instead of using the connected wallet.
// Address of the wallet who owns the funds
const owner = "{{wallet_address}}";
// Address of the wallet to check token allowance
const spender = "{{wallet_address}}";
const allowance = await contract.erc20.allowanceOf(owner, spender);
Configuration
owner
The address of the wallet that owns the funds.
Must be a string
.
const allowance = await contract.erc20.allowanceOf(
"{{wallet_address}}", // owner
"{{wallet_address}}", // spender
);
spender
The address of the wallet to check the allowance of.
Must be a string
.
const allowance = await contract.erc20.allowanceOf(
"{{wallet_address}}", // owner
"{{wallet_address}}", // spender
);
Return Value
A CurrencyValue
object is returned with the allowance available in the value
property.
{
value: BigNumber;
symbol: string;
name: string;
decimals: number;
displayValue: string;
}
balance
View the balance (i.e. number of tokens) the connected wallet has in their wallet from this contract.
const balance = await contract.erc20.balance();
Configuration
Return Value
A CurrencyValue
object is returned with the allowance available in the value
property.
{
value: BigNumber;
symbol: string;
name: string;
decimals: number;
displayValue: string;
}
balanceOf
The same as balance
, but allows you to specify the wallet address to check, instead of using the connected wallet.
// Address of the wallet to check token balance
const walletAddress = "{{wallet_address}}";
const balance = await contract.erc20.balanceOf(walletAddress);
Configuration
address
The address of the wallet to check the balance of.
Must be a string
.
const balance = await contract.erc20.balanceOf(
"{{wallet_address}}",
);
Return Value
A CurrencyValue
object is returned with the allowance available in the value
property.
{
value: BigNumber;
symbol: string;
name: string;
decimals: number;
displayValue: string;
}
burn
Burn tokens held by the connected wallet.
// The amount of this token you want to burn
const amount = 1.2;
const txResult = await contract.erc20.burn(amount);
Configuration
amount
The amount of this token you want to burn.
Must be a string
or a number
.
const txResult = await contract.erc20.burn(
1.2, // The amount of tokens to burn (e.g. 1.2)
);
burnFrom
Burn tokens held by a specified wallet (requires allowance
).
// Address of the wallet sending the tokens
const holderAddress = "{{wallet_address}}";
// The amount of this token you want to burn
const amount = 1.2;
const txResult = await contract.erc20.burnFrom(holderAddress, amount);
Configuration
holder
The address of the wallet holding to burn tokens from.
Must be a string
.
const txResult = await contract.erc20.burnFrom(
"{{wallet_address}}", // The address of the wallet holding the tokens to burn
1.2, // The amount of tokens to burn (e.g. 1.2)
);
amount
The amount of this token you want to burn.
Must be a string
or a number
.
const txResult = await contract.erc20.burnFrom(
"{{wallet_address}}", // The address of the wallet holding the tokens to burn
1.2, // The amount of tokens to burn (e.g. 1.2)
);
canClaim
Check if tokens are currently available for claiming, optionally specifying if a specific wallet address can claim.
const canClaim = await contract.erc20.claimConditions.canClaim("{{quantity}}");
Configuration
quantity (required)
The amount of tokens to claim.
This checks to see if the specified amount of tokens are available for claiming. i.e.:
- There is sufficient quantity available for claiming.
- This amount of tokens can be claimed in a single transaction.
Must be a string
or number
.
addressToCheck (optional)
The wallet address to check if it can claim tokens.
This considers all aspects of the active claim phase, including allowlists, previous claims, etc.
Must be a string
.
Return Value
Returns a boolean
indicating if the specified amount of tokens can be claimed or not.
boolean;
claim
Claim a specified number of tokens to the connected wallet.
const txResult = await contract.erc20.claim("{{amount}}");
Configuration
amount (required)
The amount of tokens to claim.
Must be a string
or number
.
options (optional)
Customizable ClaimOptions
object that can be used to override the default behaviour of the claim.
There are three options available:
checkERC20Allowance
- Whether to check the ERC20 allowance of the sender, defaults to true.currencyAddress
- The currency to pay for each token claimed, defaults toNATIVE_TOKEN_ADDRESS
for native currency.pricePerToken
- The price to pay for each token claimed. Not relevant when using claim conditions.
const txResult = await contract.erc20.claim("{{amount}}", {
checkERC20Allowance: false, // Set to true if you want to check ERC20 allowance
currencyAddress: "{{currency_contract_address}}",
pricePerToken: "{{price}}",
});
claimTo
The same as claim
, but allows specifying the recipient address rather than using the connected wallet.
const txResult = await contract.erc20.claimTo("{{recipient}}", "{{amount}}");
Configuration
recipient (required)
The wallet address to receive the claimed tokens.
Must be a string
.
amount (required)
The amount of tokens to claim.
Must be a string
or number
.
options (optional)
Customizable ClaimOptions
object that can be used to override the default behaviour of the claim.
See claim
for more details.
get
Get the metadata of the token smart contract, such as the name, symbol, and decimals.
const metadata = await contract.erc20.get();
Configuration
Return Value
{
symbol: string; // ticker, e.g. "ETH"
name: string; // Name of the token, e.g. "Ether"
decimals: number; // Number of decimals, e.g. 18
}
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 - Permissions
Get a list of wallet addresses that are members of a given role.
const members = await contract.roles.get("{{role_name}}");
Configuration
get - PlatformFee
Get the platform fee recipient and basis points.
const feeInfo = await contract.platformFee.get();
Configuration
Return Value
Returns an object containing the platform fee recipient and basis points.
{
platform_fee_basis_points: number;
platform_fee_recipient: string;
}
getActive - Claim Conditions
Retrieve the currently active claim phase, if any.
const activePhase = await contract.erc20.claimConditions.getActive();
Configuration
options (optional)
Provide an object containing a withAllowlist
property to include the allowlist in the response.
By default, the method will not include the allowlist in the returned data.
To include the allowlist in the returned data, set the withAllowlist
option to true
.
This will add a snapshot
property to the returned data, which contains the allowlist in an array.
const activePhase = contract?.erc20.getActive(
{
withAllowlist: true,
},
);
Return Value
If there is no active claim phase, returns undefined
.
If a claim condition is active, returns a ClaimCondition
object containing the following properties:
{
maxClaimableSupply: string;
startTime: Date;
price: BigNumber;
currencyAddress: string;
maxClaimablePerWallet: string;
waitInSeconds: BigNumber;
merkleRootHash: string | number[];
availableSupply: string;
currentMintSupply: string;
currencyMetadata: {
symbol: string;
value: BigNumber;
name: string;
decimals: number;
displayValue: string;
};
metadata?: {
[x: string]: unknown;
name?: string | undefined;
} | undefined;
snapshot?: {
price?: string | undefined;
currencyAddress?: string | undefined;
address: string;
maxClaimable: string;
}[] | null | undefined;
}
getAll - Claim Conditions
Get all the claim phases configured on the drop contract.
const claimPhases = await contract.erc20.claimConditions.getAll();
Configuration
options (optional)
Optionally return the allowlist with each claim phase.
See getActive
configuration for more details.
Return Value
Returns an array of ClaimCondition
objects.
{
maxClaimableSupply: string;
startTime: Date;
price: BigNumber;
currencyAddress: string;
maxClaimablePerWallet: string;
waitInSeconds: BigNumber;
merkleRootHash: string | number[];
availableSupply: string;
currentMintSupply: string;
currencyMetadata: {
symbol: string;
value: BigNumber;
name: string;
decimals: number;
displayValue: string;
};
metadata?: {
[x: string]: unknown;
name?: string | undefined;
} | undefined;
snapshot?: {
price?: string | undefined;
currencyAddress?: string | undefined;
address: string;
maxClaimable: string;
}[] | null | undefined;
}[]
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[]>>
getClaimIneligibilityReasons
Get an array of reasons why a specific wallet address is not eligible to claim tokens, if any.
const reasons = await contract.erc20.claimConditions.getClaimIneligibilityReasons(
"{{quantity}}", // Quantity of tokens to claim
"{{wallet_address}}", // Wallet address to check
);
Configuration
quantity (required)
The amount of tokens to check if the wallet address can claim.
Must be a string
or number
.
addressToCheck (optional)
The wallet address to check if it can claim tokens.
Must be a string
.
Return Value
Returns an array of ClaimEligibility
strings, which may be empty.
For example, if the user is not in the allowlist, this hook will return ["This address is not on the allowlist."]
.
If the user is eligible to claim tokens, the hook will return an empty array.
ClaimEligibility[]
// ClaimEligibility Enum
export enum ClaimEligibility {
NotEnoughSupply = "There is not enough supply to claim.",
AddressNotAllowed = "This address is not on the allowlist.",
WaitBeforeNextClaimTransaction = "Not enough time since last claim transaction. Please wait.",
AlreadyClaimed = "You have already claimed the token.",
NotEnoughTokens = "There are not enough tokens in the wallet to pay for the claim.",
NoActiveClaimPhase = "There is no active claim phase at the moment. Please check back in later.",
NoClaimConditionSet = "There is no claim condition set.",
NoWallet = "No wallet connected.",
Unknown = "No claim conditions found.",
}
getClaimTransaction
Construct a claim transaction without executing it. This is useful for estimating the gas cost of a claim transaction, overriding transaction options and having fine grained control over the transaction execution.
const claimTransaction =
await contract.erc20.claimConditions.getClaimTransaction(
"{{wallet_address}}",
"{{quantity}}",
);
Configuration
getClaimerProofs
Returns allowlist information and merkle proofs for a given wallet address. Returns null
if no proof is found for the given wallet address.
const claimerProofs = await contract.erc20.claimConditions.getClaimerProofs(
"{{wallet_address}}",
);
Configuration
getRecipient
Get the primary sale recipient.
const salesRecipient = await contract.sales.getRecipient();
Configuration
grant - Permissions
Make a wallet a member of a given role.
const txResult = await contract.roles.grant(
"{{role_name}}",
"{{wallet_address}}",
);
Configuration
normalizeAmount
Convert a number of tokens to a number of wei.
const amount = 100;
const weiAmount = await contract.erc20.normalizeAmount(amount);
Configuration
revoke - Permissions
Revoke a given role from a wallet.
const txResult = await contract.roles.revoke(
"{{role_name}}",
"{{wallet_address}}",
);
Configuration
set - Claim Conditions
Overwrite the claim phases on the drop contract.
const txResult = await contract.erc20.claimConditions.set([
{
metadata: {
name: "Phase 1", // The name of the phase
},
currencyAddress: "0x...", // The address of the currency you want users to pay in
price: 1, // The price of the token in the currency specified above
maxClaimablePerWallet: 1, // The maximum number of tokens a wallet can claim
maxClaimableSupply: 100, // The total number of tokens that can be claimed in this phase
startTime: new Date(), // When the phase starts (i.e. when users can start claiming tokens)
waitInSeconds: 60 * 60 * 24 * 7, // The period of time users must wait between repeat claims
snapshot: [
{
address: "0x...", // The address of the wallet
currencyAddress: "0x...", // Override the currency address this wallet pays in
maxClaimable: 5, // Override the maximum number of tokens this wallet can claim
price: 0.5, // Override the price this wallet pays
},
],
merkleRootHash: "0x...", // The merkle root hash of the snapshot
},
]);
Configuration
price
The price per token in the currency specified above.
The default value is 0
.
maxClaimablePerWallet
The maximum number of tokens a wallet can claim.
The default value is unlimited
.
maxClaimableSupply
The total number of tokens that can be claimed in this phase.
For example, if you lazy mint 1000 tokens and set the maxClaimableSupply
to 100,
then only 100 tokens will be claimable in this phase, leaving 900 tokens to be claimed in the next phases (if you have any).
This is useful for "early bird" use cases, where you allow users to claim a limited number of tokens at a discounted price during the first X amount of time.
startTime
When the phase starts (i.e. when users can start claiming tokens).
The default value is immediately.
waitInSeconds
The amount of time between claims a wallet must wait before they can claim again.
The default value is 0
, meaning users can claim again immediately after claiming.
snapshot
A list of wallets that you want to override the default claim conditions for.
Wallet addresses within this list can be set to pay in a different currency, have a different price, and have a different maximum claimable amount.
{
address: string;
currencyAddress?: string;
maxClaimable?: number;
price?: number;
}
Learn more about improved claim conditions.
merkleRootHash
If you want to provide your own merkle tree for your snapshot, provide the merkle root hash here.
This is only recommended for advanced use cases.
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 - PlatformFee
Set the platform fee recipient and basis points.
const txResult = await contract.platformFees.set({
platform_fee_basis_points: 100,
platform_fee_recipient: "0x123",
});
Configuration
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
},
);
setAllowance
Grant allowance to another wallet address to spend the connected wallet's funds (of this token).
// Address of the wallet to allow transfers from
const spenderAddress = "0x...";
// The number of tokens to give as allowance
const amount = 100;
await contract.erc20.setAllowance(spenderAddress, amount);
Configuration
setRecipient
Set the primary sale recipient.
await contract.sales.setRecipient("{{wallet_address}}");
Configuration
totalSupply
Get the number of tokens in circulation for this contract.
const balance = await contract.erc20.totalSupply();
Configuration
Return Value
A CurrencyValue
object is returned with the allowance available in the value
property.
{
value: BigNumber;
symbol: string;
name: string;
decimals: number;
displayValue: string;
}
transfer
Transfer tokens from the connected wallet to another wallet.
// Address of the wallet you want to send the tokens to
const toAddress = "0x...";
// The amount of tokens you want to send
const amount = 0.1;
await contract.erc20.transfer(toAddress, amount);
Configuration
transferBatch
Transfer multiple tokens from the connected wallet to multiple wallets.
const txResult = await contract.erc20.transferBatch([
{
amount: 1,
toAddress: "0x123",
},
{
amount: 2,
toAddress: "0x456",
},
]);
Configuration
#### args
An array of objects, each containing a `toAddress` and an `amount` property.
- The `toAddress` property must be a `string`, and is the wallet address you want to send the tokens to.
- The `amount` property must be a `string`, `number`, or `BigNumber`, and is the amount of tokens you want to send to the `toAddress`
transferFrom
The same as transfer
, but allows you to specify the wallet address to send the tokens from,
instead of using the connected wallet.
This is only possible if the wallet initiating this transaction has been given allowance to transfer the tokens of the fromAddress
.
// Address of the wallet sending the tokens
const fromAddress = "{{wallet_address}}";
// Address of the wallet you want to send the tokens to
const toAddress = "0x...";
// The number of tokens you want to send
const amount = 1.2;
// Note that the connected wallet must have approval to transfer the tokens of the fromAddress
await contract.erc20.transferFrom(fromAddress, toAddress, amount);
Configuration
from
The address of the wallet to send the tokens from.
Must be a string
.
await contract.erc20.transferFrom(
"{{wallet_address}}",
"{{wallet_address}}",
1.2,
);
to
The address of the wallet to send the tokens to.
Must be a string
.
await contract.erc20.transferFrom(
"{{wallet_address}}",
"{{wallet_address}}",
1.2,
);
amount
The amount of tokens to send.
Can be a number
or a string
.
await contract.erc20.transferFrom(
"{{wallet_address}}",
"{{wallet_address}}",
1.2,
);
update - Claim Conditions
Update a single claim phase on the drop contract, by providing the index of that phase and the new phase configuration.
The index
is the position of the phase in the list of phases you have made, starting from zero.
e.g. if you have two phases, the first phase has an index of 0
and the second phase has an index of 1
.
const txResult = await contract.erc20.claimConditions.update(
0, // The index of the phase to update
{
metadata: {
name: "Phase 1", // The name of the phase
},
currencyAddress: "0x...", // The address of the currency you want users to pay in
price: 1, // The price of the token in the currency specified above
maxClaimablePerWallet: 1, // The maximum number of tokens a wallet can claim
maxClaimableSupply: 100, // The total number of tokens that can be claimed in this phase
startTime: new Date(), // When the phase starts (i.e. when users can start claiming tokens)
waitInSeconds: 60 * 60 * 24 * 7, // The period of time users must wait between repeat claims
snapshot: [
{
address: "0x...", // The address of the wallet
currencyAddress: "0x...", // Override the currency address this wallet pays in
maxClaimable: 5, // Override the maximum number of tokens this wallet can claim
price: 0.5, // Override the price this wallet pays
},
],
merkleRootHash: "0x...", // The merkle root hash of the snapshot
},
);
Configuration
See set
configuration for more details.
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}}",
);