Function Call Drop
Introduction
In this tutorial, you are going to learn how to create a Function Call Drop from scratch. Similar to how the other drops can be claimed by both new and existing users, FC drops are a great onboarding tool. The difference, is that FC drops can invoke methods on external smart contracts when the link is claimed. This allows for a ton of flexibility and use-cases such as auto-registering users into a DAO as part of the onboarding process.
In this tutorial, the function call will be to Lazy Mint an NFT.
To learn more about what the FC drop, see the concepts page
Prerequisites
For the basic tutorials, you can choose to run the scripts on your own machine. To do so, you must have the following:
With this tutorial, you can either create your own script by following along, or view the completed script available in the Keypom Documentation Examples repo.
Creating your Project
In this section, you're going to create your project and install the SDK to prepare for the tutorial. If you have a completed script and have installed the SDK, you can skip forward.
First, you need to give your project a home.
mkdir my-keypom-project && cd my-keypom-project
Next, you'll want to create a default package.json file using the following command. You can accept all default values.
npm init
At this point, your project structure should look like this.
/my-keypom-project
├── package.json
If you open package.json, you should see this.
Default package.json
{
"name": "my-keypom-project",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "",
"license": "ISC"
}
The next step is to create an empty JavaScript file.
- Mac OS/Linux
- Windows
touch fc-keypom.js
fsutil file createnew fc-keypom.js 0
Finally, the last step is to install the Keypom JS SDK.
npm install @keypom/core
After installing the SDK, your package.json file should now look slightly different.
package.json after installing the SDK
{
"name": "my-keypom-project",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "",
"license": "ISC",
"dependencies": {
"@keypom/core": "^1.0.0"
}
}
With these steps complete, your project folder should look like this.
/my-keypom-project
├── fc-keypom.js
├── package.json
├── package-lock.json
├── node_modules
│ └── keypom-js
│ └── ...
You are now ready to begin creating your drop!
Breaking Down the Problem
A Function Call Drop is Keypom's most powerful drop type. A brief breakdown of how an FC drop works is as follows:
For every key-use, a set of functions is called in the order that they are defined. For multi-use keys, this set can vary across different key uses.
An example scenario for a multi-use key can be seen below.
| Key Use | Functions called during nth Key Use |
|---|---|
| Key Use 1 | nft_mint |
| Key Use 2 | sign_message, update_message |
| Key Use 3 | mint_fungible_tokens |
In this tutorial, the key will be single use and only call nft_mint.
The process of creating an FC drop is similar to the other drop types:
1) Connect to the NEAR blockchain
2) Create drop with function call data
The following skeleton code can be used as a starting point:
// Each of the two methods to create this drop will have their own unique set of imports
// Imports used in the Keypom SDK method:
const { initKeypom, createDrop, getEnv, formatLinkdropUrl } = require("@keypom/core");
const { parseNearAmount } = require("@near-js/utils");
const { UnencryptedFileSystemKeyStore } = require("@near-js/keystores-node");
const { Near } = require("@near-js/wallet-account");
const { Account } = require("@near-js/accounts");
const path = require("path");
const homedir = require("os").homedir();
// Imports used in the NEAR-API-JS method:
const { parseNearAmount } = require("@near-js/utils");
const { KeyPair } = require("@near-js/crypto")
const { UnencryptedFileSystemKeyStore } = require("@near-js/keystores-node");
const { Near } = require("@near-js/wallet-account");
const { Account } = require("@near-js/accounts");
const path = require("path");
const homedir = require("os").homedir();
async function fcDropKeypom(){
// STEP 1: Initiate a NEAR connection.
// STEP 2: Create the drop with function call data.
}
fcDropKeypom()
Getting Started
In this section, you'll be addressing the first step: connecting to NEAR.
This is done with NEAR-API-JS and consists of:
1) Create a Keystore, which stores your access keys used to sign transactions
- select a network, either
testnetormainnet - choose a location where the keypairs live, either a folder on your local machine, or in-memory
2) Define a NEAR configuration using the Keystore
3) Use the configuration to initialize a connection to NEAR
More information about this process can be found here.
For simplicity, this tutorial will choose a file-based keystore and point to the ~/.near-credentials folder on your local machine since this is where most of your keys are stored. For more information about KeyStores, visit NEAR's official docs.
loading...
Creating Drop with Function Call Data
In this section, you'll learn about the process of creating an FC drop using the SDK.
This process starts with calling the initKeypom function and will always be the first function you call to interact with the Keypom SDK.
initKeypom initializes the SDK to allow for interactions with the Keypom smart contracts. Without it, none of the other SDK functions would work as expected. If a NEAR connection is not already present, it will initialize a new one for you. More info on the initKeypom function can be found here.
After initKeypom is called, the FC Drop can be created by calling createDrop and adding an fcData parameter.
Recall that the private keys being generated using createDrop are used to store the assets. These keys are then embedded within a link.
In an FC Drop, the assets consist of a set of invokable methods and optional $NEAR.
The primary task in creating the Function Call Drop is to define fcData. It is an object containing a methods field that outlines what methods should be called for a given key use:
fcData
└── methods
For multi-use keys, each specific use can have a different set of methods that will be called. These methods are executed sequentially and not in parallel. As an example, a key with 3 uses can be seen:
nft_mintnullcreate_account_advanced,setup,nft_mint
The first time the key is used, an NFT will be minted. The second use will simply advance the key and nothing will be called. The third time the key is used, it will first call create_account_advanced. Once that's finished it will call the setup method and then finally nft_mint.
This is represented with a 2D array, where each inner is the set of methods per key use. The above example would be represented as:
methods: [
[
"nft_mint"
],
null,
[
"create_account_advanced",
"setup",
"nft_mint"
]
]
Every method listed represents a function call and requires the following parameters:
receiverId: The contract receiving the function call.methodName: The function to be called on the receiver contract.args: A stringified JSON object of all the arguments to be passed intomethodName.attachedDeposit: The yoctoNear deposit attached to the function call when the key is used.
In this tutorial only one function call will be made: nft_mint in order to lazy mint an NFT.
Including the fcData parameter categorizes this as an FC drop. Without it, the Keypom Protocol would treat this drop as a Simple Drop. More information on the fcData parameter can be found here.
To see what the SDK is doing behind the scenes, a NEAR-API-JS equivalent NodeJS script has been provided.
- 🔑 Keypom SDK
- 💻 NEAR-API-JS
loading...
loading...
Creating Linkdrops
The last step in this process is to create the links themselves so that you can easily distribute the assets to people. This is done by embedding the private key, containing the $NEAR, into the link along with the Keypom contract ID.
With the Keypom SDK, this is all neatly wrapped up in the function formatLinkdropUrl. You just need to provide the base URL format and the private key you wish to embed.
loading...
Complete Code
Now that everything has been put together, the final code can be seen below.
- 🔑 Keypom SDK
- 💻 NEAR-API-JS
loading...
loading...
Testing
Running the Script
Here, you'll learn how to run the code that was just covered, and what to expect.
To view the completed code, clone the Keypom Docs Examples repository and navigate to the basic-tutorials/fc-drop.
git clone https://github.com/keypom/keypom-docs-examples.git && cd keypom-docs-examples/basic-tutorials/fc-drop
From there, you can and open the fc-example.js file.
To run the code you just cloned, return to the keypom-docs-examples directory and install all the necessary packages.
cd .. && cd .. && yarn
Prior to running these scripts, ensure you replace all instances of keypom-docs-demo.testnet in the script with the credentials of your account found in your ~/.near-credentials folder
From there, you can run this FC Drop script that was made in this tutorial using the following command:
yarn basic:fc:keypom
The SDK script is being tested here; use yarn basic:fc:naj to test the NEAR-API-JS script instead.
This should return a successful drop creation and console log a Public Key and Linkdrop
Public Keys: [ 'ed25519:55FkiRc4J3c1zLgzuTYxJMebVrpraXU3P7zPymDtbssN' ]
Linkdrops: [
'https://testnet.mynearwallet.com/linkdrop/v2.keypom.testnet/2BB8cx2xaKzY1ENBCoVz7bTFUgq8Gx6Ar27D5PbCv39NnZLfWxw3XqWr37HZ1xm3KdQ5uCt8hvt6ztF1eGBQC1Hi'
]
Keypom Contract Explorer Link: explorer.testnet.near.org/accounts/v2.keypom.testnet.com
To see the full console log from this drop creation, see the expandable section below.
Console Log of Test
Receipts: 4MTrVP1cvemzA1XhmX4hHErYvmcgMCgfrXydwNTeez3Y, 8LDCtYSsN5ccFY5udxbYqoVzmxyubqZBRLvMR33FUREN
Log [v2.keypom.testnet]: Current Block Timestamp: 1682352446955649219
Log [v2.keypom.testnet]: 21 calls with 105000000000000 attached GAS. Pow outcome: 1.8602935. Required Allowance: 20248156910387200000000
Log [v2.keypom.testnet]: Total required storage Yocto 14230000000000000000000
Log [v2.keypom.testnet]: Current balance: 9.3089748,
Required Deposit: 2.0354781,
total_required_storage: 0.01423,
Drop Fee: 0,
Key Fee: 0 Total Key Fee: 0,
allowance: 0.0202481 total allowance: 0.0202481,
access key storage: 0.001 total access key storage: 0.001,
deposits less none FCs: 1 total deposits: 1 lazy registration: false,
deposits for FCs: 1 total deposits for FCs: 1,
uses per key: 1
None FCs: 0,
length: 1
GAS to attach: 100000000000000
Log [v2.keypom.testnet]: New user balance 7.2734966
Log [v2.keypom.testnet]: Fees collected 0
Public Keys: [ 'ed25519:55FkiRc4J3c1zLgzuTYxJMebVrpraXU3P7zPymDtbssN' ]
Linkdrops: [
'https://testnet.mynearwallet.com/linkdrop/v2.keypom.testnet/2BB8cx2xaKzY1ENBCoVz7bTFUgq8Gx6Ar27D5PbCv39NnZLfWxw3XqWr37HZ1xm3KdQ5uCt8hvt6ztF1eGBQC1Hi'
]
Keypom Contract Explorer Link: explorer.testnet.near.org/accounts/v2.keypom.testnet.com
Claiming and Explorer Transactions
Once you click the link, it will take you to the following NEAR Wallet page, where you will have the choice to claim with an existing account or create a new one.
To check the transactions, click the final link in the console log when you run the script.
Keypom Contract Explorer Link: https://explorer.testnet.near.org/accounts/v2.keypom.testnet
From there, you should be able to see the create_drop and claim transactions.
Within the claim transaction, you can also see that nft_mint was called on the nft.examples.testnet contract.
This can be confirmed by visiting the "Collectibles" tab in your NEAR wallet. You should see the newly minted NFT in your wallet.
Conclusion
In this tutorial, you learned the how to create a function call drop using the fcData parameter. Once the drop was created, you constructed a valid linkdrop using the private keys in order to claim the assets.
Now that you've had a good introduction to creating all 4 Keypom drop types, feel free to modify the scripts created or move on to the Advanced Tutorials for more challenging and practical examples.