Hello! In this article, I will show you how to write and run a regular dApp on a Waves node. Consider the necessary tools, methods and development example.
The scheme for developing dApps and ordinary applications is almost the same:
We write the code
Writing automated testing
Run the application
We are testing
Tools
1. docker to run the node and Waves Explorer
If you don't want to run a node, you can skip this step. After all, there is a test and experimental network. But without deploying your own node, the testing process can be delayed.
You will constantly need new accounts with test tokens. The testnet faucet transfers 10 WAVES every 10 minutes.
The average block time in the test network is 1 minute, in the node - 15 seconds. This is especially noticeable when a transaction requires multiple confirmations.
Aggressive caching is possible in public test nodes.
They may also be temporarily unavailable due to maintenance.
Further, I will assume that you are working with your node.
Install Surfboard, a tool that will allow you to run tests on an existing node.
npm install -g @waves/surfboard
3. Visual Studio Code Plugin
This step is optional if you are not an IDE fan and prefer text editors. All the necessary tools are command line utilities. If you are using vim, check out the plugin vim-ride.
Download and install Visual Studio Code: https://code.visualstudio.com/
docker run -d -e API_NODE_URL=http://localhost:6869 -e NODE_LIST=http://localhost:6869 -p 3000:8080 wavesplatform/explorer
Open a browser and go to http://localhost:3000. See how quickly an empty local node chain is built.
Waves Explorer displays local node instance
RIDE structure and Surfboard tool
Create an empty directory and run the command in it
surfboard init
The command initializes the directory with the project structure, hello world applications and tests. If you open this folder with VS Code, you will see:
Surfboard.config.json
Under the ./ride/ folder, you will find a single wallet.ride file - the directory where the dApp code is located. We will briefly analyze dApp in the next block.
Under the ./test/ folder you will find the *.js file. This is where tests are stored.
./surfboard.config.json - configuration file for running tests.
Envs is an important section. Each environment is configured like this:
The REST API endpoint of the node that will be used to launch the dApp and the CHAIN_ID of the network.
Passphrase for the token account that will be the source of your test tokens.
As you can see, surfboard.config.json supports multiple environments by default. By default, the local environment is set (the defaultEnv key is a variable parameter).
Wallet-demo application
This section is not a reference to the RIDE language. Rather, a look at the application that we are deploying and testing in order to better understand what is happening in the blockchain.
Consider a simple Wallet-demo application. Everyone can send tokens to the dApp address. You can withdraw only your own WAVES. Two @Callable functions are available via InvokeScriptTransaction:
deposit(), which requires an attached payment in WAVES
withdraw(amount: Int), which returns tokens
Throughout the dApp life cycle, the structure (address → amount) will be maintained:
Action
result state
initial
empty
Alice deposits 5 WAVES
alice-address → 500000000
Bob deposits 2 WAVES
alice-address → 500000000
bob-address → 200000000
Bob withdraws 7 WAVES
DENIED!
Alice withdraws 4 WAVES
alice-address → 100000000
bob-address → 200000000
Here is the code to fully understand the situation:
# In this example multiple accounts can deposit their funds and safely take them back. No one can interfere with this.
# An inner state is maintained as mapping `address=>waves`.
{-# STDLIB_VERSION 3 #-}
{-# CONTENT_TYPE DAPP #-}
{-# SCRIPT_TYPE ACCOUNT #-}
@Callable(i)
func deposit() = {
let pmt = extract(i.payment)
if (isDefined(pmt.assetId))
then throw("works with waves only")
else {
let currentKey = toBase58String(i.caller.bytes)
let currentAmount = match getInteger(this, currentKey) {
case a:Int => a
case _ => 0
}
let newAmount = currentAmount + pmt.amount
WriteSet([DataEntry(currentKey, newAmount)])
}
}
@Callable(i)
func withdraw(amount: Int) = {
let currentKey = toBase58String(i.caller.bytes)
let currentAmount = match getInteger(this, currentKey) {
case a:Int => a
case _ => 0
}
let newAmount = currentAmount - amount
if (amount < 0)
then throw("Can't withdraw negative amount")
else if (newAmount < 0)
then throw("Not enough balance")
else ScriptResult(
WriteSet([DataEntry(currentKey, newAmount)]),
TransferSet([ScriptTransfer(i.caller, amount, unit)])
)
}
@Verifier(tx)
func verify() = false
The VSCode plugin supports continuous compilation while editing a file. Therefore, you can always watch for errors in the PROBLEMS tab.
If you want to use a different text editor when compiling the file, use
surfboard compile ride/wallet.ride
This will output a base64 string of compiled RIDE code.
Test script for 'wallet.ride'
Let's look at test file. Powered by JavaScript's Mocha framework. There is a "Before" function and three tests:
"Before" funds multiple accounts through MassTransferTransaction, compiles the script, and deploys it to the blockchain.
"Can deposit" sends an InvokeScriptTransaction to the network, activating the deposit() function for each of the two accounts.
"Can't withdraw more than was deposited" tests that no one can steal someone else's tokens.
"Can deposit" checks that withdrawals are processed correctly.
Running Tests from Surfboard and Analyzing Results in Waves Explorer
To run the test run
surfboard test
If you have multiple scripts (for example, you need a separate deployment script), you can run
surfboard test my-scenario.js
Surfboard will collect the test files in the ./test/ folder and run the script in the node that is configured in surfboard.config.json. After a few seconds, you will observe something like this:
wallet test suite
Generating accounts with nonce: ce8d86ee
Account generated: foofoofoofoofoofoofoofoofoofoofoo#ce8d86ee - 3M763WgwDhmry95XzafZedf7WoBf5ixMwhX
Account generated: barbarbarbarbarbarbarbarbarbar#ce8d86ee - 3MAi9KhwnaAk5HSHmYPjLRdpCAnsSFpoY2v
Account generated: wallet#ce8d86ee - 3M5r6XYMZPUsRhxbwYf1ypaTB6MNs2Yo1Gb
Accounts successfully funded
Script has been set
√ Can deposit (4385ms)
√ Cannot withdraw more than was deposited
√ Can withdraw (108ms)
3 passing (15s)
Hooray! Tests passed. Now let's take a look at what happens when using the Waves Explorer: look at the blocks or insert one of the above addresses into the search (for example, the corresponding wallet#. There you can find transaction history, dApp state, decompiled binary.
wave explorer. An application that has just been deployed.
2. Import your network token passphrase? For simplicity, use the initial seed of your node: waves private node seed with waves tokens. Address: 3M4qwDomRabJKLZxuXhwfqLApQkU592nWxF.