Faucet: Easy Access to Free Blockchain Assets
Last updated
Last updated
When developing on the blockchain, using real money is often not ideal. Each iteration on the network can incur costs, making development and deployment significantly more expensive than it should be.
This is where faucets come inโthey provide a free way to issue assets on the network, enabling you to experiment and develop without adding unnecessary expenses to your project.
Learn how faucets simplify blockchain development and help you take a simple idea from concept to production without investing more than your development time.
In this article, weโll explore how to create a faucet for a custom asset on the Stellar network.
Weโll guide you through the process step by step, from setting up the necessary tools to designing a faucet that distributes your asset efficiently and securely. Whether youโre building for testing, development, or community engagement, this tutorial will help you unlock the full potential of faucets for your Stellar-based projects. Letโs dive in!
For this project, we will create a faucet to distribute a custom asset. This will be helpful when working with the Stellar blockchain.
First, navigate to your favorite projects folder and create a new folder for this project.
Next, we will initialize an empty npm project and install some dependencies. We will use @stellar/stellar-sdk to communicate with the blockchain, express to expose an endpoint for distributing our custom asset and dotenv to load our environment variables.
It's essential to configure environment variables for managing sensitive data like API keys and secret keys. This ensures that sensitive information is not hardcoded into your source code, maintaining security and flexibility.
Steps to Create and Configure the Environment File
Create an Environment File
Open the newly created .env file and add the necessary configuration details. Here's an example of what it might look like:
Next, weโll need an entry point to load our variables. To achieve this, weโll create a folder containing our environment file:
To load environment variables, add the following code to the environment.js file:
Now, we will create an index.js file to expose our endpoint. To do this, copy the following lines.
To expose our Friendbot, we will use Express to create a basic endpoint.
With the server running, letโs start with the faucet!
First, you will need two accounts already funded with XLM (the native token) on the blockchain. These accounts will act as the Issuer account and the Distributor account. To create them, you can go to the Stellar Laboratory and generate two accounts.
For each account, generate a new keypair, press โFund Account with Friendbot,โ and store both the Public Key and the Secret Key.
Now we are ready to continue our journey.
Create an src folder to store our Friendbot service, which will assist us with this!
Paste the code below inside the friendbotService.js file:
Let's update our code to expose our Friendbot endpoint to the world!
To do this, we will create a POST - /friendbot endpoint that accepts a query parameter for the address we want to fund with our custom token.
The final URL should look like this: POST - /friendbot?address=GD3V.....
Now let's move on to our friendbotService.js file again and create our logic. Paste the following code inside the file:
Now that we have this, letโs take a deeper look at what is happening.
As mentioned in our previous article, there is no direct way to create an Asset on the blockchain using Stellar Classic. Instead, we need to create a payment operation from the issuer.
We now have two functions: fundDistributorAccount and fundAccount. The first will fund our custom token into a distributor account. As a good practice, it is not advisable for the issuer to send the tokens directly to the address we want to fund (refer to the assets blog for more details).
Let's take a look inside the fundDistributorAccount function:
Here, we have the issued asset that we want to distribute with our Friendbot.
The asset is composed of a code (alphanumeric4 or alphanumeric12) and the issuer account.
After that, we load the account of the issuer, who is the one that should mint the custom token into the distributor account.
We create both the trustline for our distributor (for trustline references, check our article on Assets) and the payment operation, making the latter responsible for minting โ by "mint," we mean creating this asset and storing its existence on the blockchain โ the asset to the distributor.
Afterward, we create our transaction operation. This is responsible for building the entire transaction with all the details of its composition. Note that we are adding the change trust operation and the payment operation afterward. These operations must be in the correct order, as sending a token to an account that does not have the corresponding trustline to the asset will cause the entire transaction to fail, and it will be rolled back from the blockchain.
Once we have built our transaction, it's time to sign it. The transaction must be signed by the two account keypairs, as we are involving two different operations within the same account: the trustline creation from the distributor account and the payment operation from the issuer account to the distributor. By doing it this way, if any of the signatures are missing, we will encounter an error.
When everything is in order, we can send the transaction to the network and check the results.
We have our distributor account with the corresponding funds to transfer into the account we want to fund with our faucet.
Now, let's talk about the fundAccount function.
We can see that the first thing the function does is ensure that the distributor account has enough funds to transfer into our account by invoking our fundDistributorAccount function.
After that, we load the information of the distributor account, build our payment transaction, and finally send the asset to the account we want to fund, signing the transaction.
We are ready to send our transaction, but wait a second! Our account is still missing the trustline for the incoming asset, and we do not want an error in our faucet. Let's take a minute and create this trustline quickly in the Laboratory!
First, we need a third account for this โ the receiver. So, let's create a new account and fund it using the testnet Friendbot of the Laboratory.
Now we can create our trustline transaction using the Laboratory.
Let's go to the Transactions tab, paste the public key of the new account into the source account, and press Fetch the sequence number. This is important because if we try to use an already used sequence number, the transaction will fail (this is not necessary when using the SDK, as the SDK handles all of this for us).
Now, we can move to the Operations section. Here, select Change Trust from the dropdown and choose Alphanumeric 4 as the asset code. We will need our issuer account to specify where our asset comes from.
Here, we add the operation and are ready to move to the Sign section. We press Sign operation in the signer, then move to the next section where we can review the details of the operation. To sign, weโll need our new account's secret key, and in the Signatures section, we'll add our secret key and press Sign transaction.
Since this is for testing purposes, I'm displaying the secret, but keep in mind that this secret key should not be available to anyone, as it allows you to sign transactions and operate on your account's behalf.
We move to the bottom of the page and press Submit in the Transaction Submitter, and after that, we press Submit transaction.
Now that we have the asset in our account, we can start using our Friendbot.
Run the server using the following command:
Should have an output like this:
We can test our faucet with curl and our publick key:
Finaly we send the transaction and if everithing went ok now we can chek our account into the laboratory and verify that our account currently has the amount of the token that we want.
Faucets play a crucial role in blockchain development by allowing developers to interact with the network without incurring real costs. In this tutorial, we explored how to create a faucet for distributing custom assets on the Stellar network, offering a simple and effective solution for testing and experimentation.
By setting up a project with Express, the Stellar SDK, and environment variables, we demonstrated how to establish a faucet that can distribute assets securely and efficiently. The step-by-step guide covered everything from creating the necessary accounts and environment setup to implementing the logic for funding accounts with custom tokens.
Whether for development, testing, or community engagement, faucets help streamline the process of building on blockchain networks, empowering developers to bring their ideas to life with minimal financial risk. By following this tutorial, you now have the tools to create a Stellar faucet tailored to your project's needs, opening up a world of possibilities for future blockchain applications.