From Part 2...
I'm going to have to defer the off-chain micropayment topic to a later blog post (part 4?). When I was researching the details I found that some pieces of the interface libraries were not dry yet. A quick call with the ThetaLabs guys verified this as of this writing. So on to the next compelling topic.
One of the things that the Theta team has done well is to focus on their key blockchain technology and leverage the broader blockchain ecosystem when it makes sense to do so. When it comes to smart contract support the Theta blockchain implements the Etherium Virtual Machine mechanism and therefore developers can use a wide range of existing smart contract development tools and examples. This is why there is minimal documentation and official Theta smart contract tools on their site. We will step through a simple Etherium smart contract but in a Theta blockchain context to show you how it's done and where is might be handled differently for the Theta blockchain.
When you are focusing on smart contract development, you will need to compile your smart contract code and then deploy it to the blockchain. A smart contract deployment is considered a send transaction from a known account(wallet) and incurs a cost in TFuel tokens. With the Theta blockchain this cost is very very small but is still required. While you could do this on the public MainNet, ThetaLabs provides a testing environment just for smart contract development and testing called the "Smart Contracts Sandbox". You can also deploy smart contracts to you own "PrivateNet" node that we set up in Part 2 of this blog series.
When I was first looking at blockchain development I was initially confused by "wallets". It seemed you could get wallet functionality by visiting a web page, installing a browser plugin, mobile phone app, or purchasing a "hardware wallet". How is is possible to keep track of where the tokens are stored I wondered? What if they get split up between wallets? What if you loose your wallet? What if you transfer them to a wallet and they never arrive? I have come to realize now that my hang-up was with the word "Wallet". In blockchain terminology a wallet is not analogous to a real world wallet where we keep our cash, credit cards, and pictures of loved ones. A blockchain wallet is really an encryptor that you completely control that allows you to facilitate interacting with an account on a particular type(Theta) of blockchain network. When a blockchain wallet is first created, it is cryptographically guaranteed to be unique in the set of networks that it is compatible with. Originally I though I'd need to create a wallet for each of Theta MainNet, SmartContract Sandbox, and PrivateNet nodes. This is not the case. The same wallet works in all places. The wallet also has a unique address that is valid across all Theta nets. However, you can't query it on a particular net until after some amount of token(Theta and/or TFuel) has been sent to it on that net. Up until that point the net hasn't ever seen your wallet's address. When you use your PrivateNet node, there are some built-in known wallets with a quantity of existing tokens on them that you can just start using(since the secrets are known to you and everyone else), If you want to create a new wallet, use the THETACLI tool. The value(ie: Token balance) is stored on the blockchain and not in your wallet itself. In fact once created, you don't even need an app or hardware key to use it. If you memorize the 12 word mnemonic used to secure your wallet, you can re-create is anywhere you need it. In addition, you can create a wallet online as well. Go to ThetaToken.org website and click Wallet.
Create a wallet by clicking "Create Wallet".
Once created, you need to decide which net you want to work with. If you want to use the MainNet, you'll actually have to pony up some real currency and get an account on an exchange and then send it to your wallet(account) on the MainNet. I won't get into the details, but search for crypto exchanges and check that they support both Theta and TFuel. But for development purposes where you don't want to run your own PrivateNet, then you'll need at least some TFuel tokens in your account on the Smart Contract Sandbox. In order to get some, you'll need to send your public wallet address to support@thetalabs.com and just ask. You could also ask someone else(me) that already has some TFuel tokens on the Smart Contract Sandbox and they'll(i'll) send you some.
You can select which net you're interacting with by using the pull-down option at the top.
And select Smart Contracts Sandbox.
Verify that it's the current net before you interact with it.
For the remainder of this blog post, we'll assume that you're running your own PrivateNet.
Make sure that you've checked out the v3.0 tag from the github repo. This tag release has some smart contract sample files in it.
From this point we'll be referring to Etherium documentation and tools and applying what we find to the Theta context. As mentioned above the Theta blockchain is EVM compatible.
In your BAS window, expand the project tree and the sol folder. Click on counter.sol file to open it in the editor window.
The code for smart contracts is written in a programming language called Solidity. Currently BAS has no support for Solidity, but we can add it by installing a plugin. Click on the extension manager icon and type "solidity" in the search box. Install and notice that the counter.sol code is now colored.
BAS now will perform syntax checking of your code and will have a context menu when you right-click on a .sol file in the editor.
If you bring up the context menu, you'll see a bunch of options that start with Solidity: Click Download compiler.
Select the version that matches the counter.sol Pragma statement. Note the unlike other development scenarios, smart contract development requires you to compile your code with a compatible VERSION of the solidity compiler. Double check the pragma statement to make sure you're picking one that is specific or within the declared range.
Now you can select Compile with configured Remote version.
If all goes well, you should see a message that indicates your compilation was successful.
Notice that not much else happens. No extra files are generated or messages shown.
It seems this extension invokes the compiler as an imbedded minified javascript and only outputs certain styles of (CSharp, FSharp, VB.net, etc) of generated output. We need something that we can use with a NodeJS module within the context of the Theta NodeJS library. I may be able to figure out how to invoke the compiler in this way, but for now I have found that I need the binary version of the compiler so that I can control its invocation from the command line. The BAS Extras extension has a command for this. Click View -> Find Command -> BAS: Install SOLC 0.5.17.
The result is the command solc downloaded and installed. You can verify this by running this command in the terminal window.
Make sure you're in the sol folder and run the prep4deploy script that will compile the .sol file and produce the desired output files.
The script will create a folder called outbin that will contain the following files. (If you haven't already, install the tree command with notroot install tree).
In order to test our application directly from BAS, we can rely on the existing deployed theta-trustee module and grab it's default environment storing it as a local file. This will allow the app to pick up the same environment as the deployed app even though we'll be running it locally. First switch into the folder that contains the CloudFoundry sample app.
Then run the de subcommand to create a default-env.json file. If you cf cli doesn't have the de subcommand, then you can install it with View -> Find Command... -> BAS: Install CF DefaultEnv Plugin.
In addition to merely running it, we might want to verify its inner working by debugging it within BAS.
Unfortunately the debugger uses a different format for reading and populating the environment in which it runs so I wrote a script that will take the default-env.json file just produced and create a .env file formatted the way the debugger prefers.
We can now run the node module locally(within BAS). Open a terminal and make sure the current directory is the trustee folder. Then run node on the server.js file.
You should see s popup that lets you know that the module is listening on local port(8080). The BTP system will map a url to your process so that you can browse to it.
Clicking Open in New Tab will do just that. You should see a simple web page in your browser.
You can see that I'm not a fan of fancy UI's. The point here is to not clutter the code with a bunch of UI framework constructs that detracts from the underlying function. Just click The Links page. Since this module is intended to be part of a Multi-Target Application(MTA), you would normally access it through an app router module to enforce authentication. We're just going to access it directly for now. I you see this output in the terminal, it's telling you that you haven't defined a password in the credstore. See the last blog post for details.
The built-in privkey can be set on line 114 and should be replaced with another mechanism in production if you don't want to use the credstore service of BTP.
If you're running in a trial account, you should check that your theta-privatenet node is up and running. First see if it's in a requested state of running.
If it's showing a state of down, then restart it.
Once it's showing running, give it a good 3 minutes for things to settle then ssh into it with cf ssh.
When things are up you should see the following when sshing in.
You can run screen to connect to the background session.
Check the out and make sure to wait until the block height is greater than 50. This is the point in the blockchain when smart contract support was enabled on this privatenet node.
In order to detach from the session use "Control a" key and then the "d" key. When back at the prompt you can exit. Note: If you hit "Control c" you'll stop the node and will need to restart it.
Remember earlier in this post when we compiled our solidity code, the script generated several files. Now we are going to consume them by initiating a smart contract deployment. Click on the deploy-last-compiled-contract link.
This will not actually perform the deploy yet, but will test that everything is correct and show you some information about the smart contract interface(the ABI). Click the Do-It line to actually perform the deploy. Notice that this time, things will take longer, but if all goes well you'll see a bunch of output including the deployedAddress.
It's important to make a note of the contract address so that you can interact with it later. There may be a way to search for existing deployed contracts, but I haven't figured that out yet(I'm still learning too). In this case.
This will read the ABI file that we just used to deploy the contract and try its best to create some links based on the interface. In this example the counter.sol contract is the one we last compiled.
First click the increment link to increment the counter state of the contract. Since this will change the state of the contract, it will take a little longer and actually cost a little TFuel.
You should see the return details and the transaction block details. Now click on the getCount link.
Since getCount is a read operation, it will return very quickly. The blockchain doesn't need to synchronize and reach consensus just to read a property of a contract.
We can see that the function returns a BigNumber that expressed in hex but is clearly 1. Keep pressing the increment() and getCount() links to increment and see the last cound.
I know that this is the simplest of smart contracts, but it's good to know how to go about debugging your code that interfaces with the smart contract. Let's set up to debug our code by creating a run profile. Click on the debug icon and then the drop-down.
Now click Add Configuration. This will bring up the launch.json configuration file in the editor and present you with a list of templates.
Pick Node.js Launch Program since the debugger is running locally(within BAS) and that where are source code is as well.
This step alone isn't sufficient for debugging. As mentioned above, the debugger runs in it's own environment and we need to simulate our module running in CloudFoundry. The run configuration needs to load the environment from the .env file and set the current directory so that it knows where to find the source files. I've created DEBUGGING.md file that has a working launch.json section that you can cut/paste into yours. Once you've done this yours might look like this.
OK, let's return to your server.js code and set a breakpoint on line 582. This is a point when handling the interact-with-last-contract link. It is checking whether an address(remember I told you to make a note) was passed in.
Also note that a new breakpoint appeared in the BREAKPOINTS section.
Now, finally we can start our module in debugger mode. Click on the green start debugging arrow.
The status bar at the bottom of the BAS window should turn orange and the debugging controls should be enabled. If you find it doesn't work, check the Debug Console for issues. Here we see that the port 8080 was already in use indicating that when we were running our module under nodejs directly, we didn't stop it. Find that terminal where it's running and do a Ctrl-C. Try debugging again.
You should get a pop-up message to open a new tab with the module. You should see 2 threads running and the restart and stop icons should be enabled. Again the bottom status bar should be orange.
Now click on the interact-with-last-contract link again. This time it should break on line 582. The line will be hi-lighted yellow to indicate it's next for execution. The THREADS and VARIABLES sections should be active and the Step-Over, Step-Into, Step-Out icons should be enabled.
For now just click on the Step-Over icon (curved arrow over dot) and see how execution would continue. You can hover over variables or expand the Local variable section to see the value of things. When you're ready to run at full speed(until the next breakpoint) then click the run icon (bar+arrow). Keep clicking links in the module or modify the browser address to change the parameters and see what happens. When you are done debugging click the stop (red square) icon (twice) and BAS status should return to blue.
I hope that I've demonstrated that BAS is a more than capable tool for performing all types of development and especially Theta Blockchain Smart Contract development when tweaked to fit the need. BTP(even trial accounts) is also up to the job of running a test PrivateNet node that will allow you to quickly get your smart contracts in shape for the Theta MainNet. As of this writing the Theta MainNet 3.0 launch is less than 30 days away and promises some interesting features such as uptime mining and TFuel staking. More details can be found at ThetaToken.org.
I'll re-commit to my promise of demonstrating the very intriguing off-chain micropayments feature of the Theta blockchain in my next installment of this blog series. Stay tuned and be sure to reach out to me if you want to be kept in the loop of my efforts with SAP and Theta blockchain by dropping me an email at andrew.lunde@sap.com .
Let me know if you have and questions or issues by leaving me a question below or better yet, asking it on the SAP community.
-Andrew
In the next blog post in this series, I'll explore the off-chain micropayments feature and implement a test to measure the performance of that approach. For the impatient, give this white-paper a read and you'll be in a great mindset for my next installment.
I'm going to have to defer the off-chain micropayment topic to a later blog post (part 4?). When I was researching the details I found that some pieces of the interface libraries were not dry yet. A quick call with the ThetaLabs guys verified this as of this writing. So on to the next compelling topic.
Does the Theta blockchain support smart contracts?
One of the things that the Theta team has done well is to focus on their key blockchain technology and leverage the broader blockchain ecosystem when it makes sense to do so. When it comes to smart contract support the Theta blockchain implements the Etherium Virtual Machine mechanism and therefore developers can use a wide range of existing smart contract development tools and examples. This is why there is minimal documentation and official Theta smart contract tools on their site. We will step through a simple Etherium smart contract but in a Theta blockchain context to show you how it's done and where is might be handled differently for the Theta blockchain.
Getting caught up in the "Nets".
When you are focusing on smart contract development, you will need to compile your smart contract code and then deploy it to the blockchain. A smart contract deployment is considered a send transaction from a known account(wallet) and incurs a cost in TFuel tokens. With the Theta blockchain this cost is very very small but is still required. While you could do this on the public MainNet, ThetaLabs provides a testing environment just for smart contract development and testing called the "Smart Contracts Sandbox". You can also deploy smart contracts to you own "PrivateNet" node that we set up in Part 2 of this blog series.
A word on Wallets and Accounts and Nets.
When I was first looking at blockchain development I was initially confused by "wallets". It seemed you could get wallet functionality by visiting a web page, installing a browser plugin, mobile phone app, or purchasing a "hardware wallet". How is is possible to keep track of where the tokens are stored I wondered? What if they get split up between wallets? What if you loose your wallet? What if you transfer them to a wallet and they never arrive? I have come to realize now that my hang-up was with the word "Wallet". In blockchain terminology a wallet is not analogous to a real world wallet where we keep our cash, credit cards, and pictures of loved ones. A blockchain wallet is really an encryptor that you completely control that allows you to facilitate interacting with an account on a particular type(Theta) of blockchain network. When a blockchain wallet is first created, it is cryptographically guaranteed to be unique in the set of networks that it is compatible with. Originally I though I'd need to create a wallet for each of Theta MainNet, SmartContract Sandbox, and PrivateNet nodes. This is not the case. The same wallet works in all places. The wallet also has a unique address that is valid across all Theta nets. However, you can't query it on a particular net until after some amount of token(Theta and/or TFuel) has been sent to it on that net. Up until that point the net hasn't ever seen your wallet's address. When you use your PrivateNet node, there are some built-in known wallets with a quantity of existing tokens on them that you can just start using(since the secrets are known to you and everyone else), If you want to create a new wallet, use the THETACLI tool. The value(ie: Token balance) is stored on the blockchain and not in your wallet itself. In fact once created, you don't even need an app or hardware key to use it. If you memorize the 12 word mnemonic used to secure your wallet, you can re-create is anywhere you need it. In addition, you can create a wallet online as well. Go to ThetaToken.org website and click Wallet.
Create a wallet by clicking "Create Wallet".
Once created, you need to decide which net you want to work with. If you want to use the MainNet, you'll actually have to pony up some real currency and get an account on an exchange and then send it to your wallet(account) on the MainNet. I won't get into the details, but search for crypto exchanges and check that they support both Theta and TFuel. But for development purposes where you don't want to run your own PrivateNet, then you'll need at least some TFuel tokens in your account on the Smart Contract Sandbox. In order to get some, you'll need to send your public wallet address to support@thetalabs.com and just ask. You could also ask someone else(me) that already has some TFuel tokens on the Smart Contract Sandbox and they'll(i'll) send you some.
You can select which net you're interacting with by using the pull-down option at the top.
And select Smart Contracts Sandbox.
Verify that it's the current net before you interact with it.
For the remainder of this blog post, we'll assume that you're running your own PrivateNet.
Back to the Smart Contract Topic.
Make sure that you've checked out the v3.0 tag from the github repo. This tag release has some smart contract sample files in it.
git checkout v3.0From this point we'll be referring to Etherium documentation and tools and applying what we find to the Theta context. As mentioned above the Theta blockchain is EVM compatible.
In your BAS window, expand the project tree and the sol folder. Click on counter.sol file to open it in the editor window.
The code for smart contracts is written in a programming language called Solidity. Currently BAS has no support for Solidity, but we can add it by installing a plugin. Click on the extension manager icon and type "solidity" in the search box. Install and notice that the counter.sol code is now colored.
BAS now will perform syntax checking of your code and will have a context menu when you right-click on a .sol file in the editor.
If you bring up the context menu, you'll see a bunch of options that start with Solidity: Click Download compiler.
Select the version that matches the counter.sol Pragma statement. Note the unlike other development scenarios, smart contract development requires you to compile your code with a compatible VERSION of the solidity compiler. Double check the pragma statement to make sure you're picking one that is specific or within the declared range.
Now you can select Compile with configured Remote version.
If all goes well, you should see a message that indicates your compilation was successful.
Notice that not much else happens. No extra files are generated or messages shown.
It seems this extension invokes the compiler as an imbedded minified javascript and only outputs certain styles of (CSharp, FSharp, VB.net, etc) of generated output. We need something that we can use with a NodeJS module within the context of the Theta NodeJS library. I may be able to figure out how to invoke the compiler in this way, but for now I have found that I need the binary version of the compiler so that I can control its invocation from the command line. The BAS Extras extension has a command for this. Click View -> Find Command -> BAS: Install SOLC 0.5.17.
The result is the command solc downloaded and installed. You can verify this by running this command in the terminal window.
solc --versionMake sure you're in the sol folder and run the prep4deploy script that will compile the .sol file and produce the desired output files.
cd ~/projects/btp-blockchain-theta/sol/
./prep4deploy ./counter.solThe script will create a folder called outbin that will contain the following files. (If you haven't already, install the tree command with notroot install tree).
In order to test our application directly from BAS, we can rely on the existing deployed theta-trustee module and grab it's default environment storing it as a local file. This will allow the app to pick up the same environment as the deployed app even though we'll be running it locally. First switch into the folder that contains the CloudFoundry sample app.
cd ~/projects/btp-blockchain-theta/cf/trusteeThen run the de subcommand to create a default-env.json file. If you cf cli doesn't have the de subcommand, then you can install it with View -> Find Command... -> BAS: Install CF DefaultEnv Plugin.
cf de theta-trusteeIn addition to merely running it, we might want to verify its inner working by debugging it within BAS.
Unfortunately the debugger uses a different format for reading and populating the environment in which it runs so I wrote a script that will take the default-env.json file just produced and create a .env file formatted the way the debugger prefers.
./default2dot We can now run the node module locally(within BAS). Open a terminal and make sure the current directory is the trustee folder. Then run node on the server.js file.
node server.jsYou should see s popup that lets you know that the module is listening on local port(8080). The BTP system will map a url to your process so that you can browse to it.
Clicking Open in New Tab will do just that. You should see a simple web page in your browser.
You can see that I'm not a fan of fancy UI's. The point here is to not clutter the code with a bunch of UI framework constructs that detracts from the underlying function. Just click The Links page. Since this module is intended to be part of a Multi-Target Application(MTA), you would normally access it through an app router module to enforce authentication. We're just going to access it directly for now. I you see this output in the terminal, it's telling you that you haven't defined a password in the credstore. See the last blog post for details.
The built-in privkey can be set on line 114 and should be replaced with another mechanism in production if you don't want to use the credstore service of BTP.
If you're running in a trial account, you should check that your theta-privatenet node is up and running. First see if it's in a requested state of running.
cf app theta-privatenetIf it's showing a state of down, then restart it.
cf restart theta-privatenetOnce it's showing running, give it a good 3 minutes for things to settle then ssh into it with cf ssh.
cf ssh theta-privatenetWhen things are up you should see the following when sshing in.
You can run screen to connect to the background session.
screen -x thetaCheck the out and make sure to wait until the block height is greater than 50. This is the point in the blockchain when smart contract support was enabled on this privatenet node.
In order to detach from the session use "Control a" key and then the "d" key. When back at the prompt you can exit. Note: If you hit "Control c" you'll stop the node and will need to restart it.
Remember earlier in this post when we compiled our solidity code, the script generated several files. Now we are going to consume them by initiating a smart contract deployment. Click on the deploy-last-compiled-contract link.
This will not actually perform the deploy yet, but will test that everything is correct and show you some information about the smart contract interface(the ABI). Click the Do-It line to actually perform the deploy. Notice that this time, things will take longer, but if all goes well you'll see a bunch of output including the deployedAddress.
It's important to make a note of the contract address so that you can interact with it later. There may be a way to search for existing deployed contracts, but I haven't figured that out yet(I'm still learning too). In this case.
deployedAddress : 0x9572ecea04fe74b642400dbb04952e91049c9b3d
Now that I've said that, I've stashed the deployedAddress in the running module's environment as well to help facilitate testing but don't rely on that. If the module crashes, it will be gone.
Click on interact-with-last-contract.
This will read the ABI file that we just used to deploy the contract and try its best to create some links based on the interface. In this example the counter.sol contract is the one we last compiled.
First click the increment link to increment the counter state of the contract. Since this will change the state of the contract, it will take a little longer and actually cost a little TFuel.
You should see the return details and the transaction block details. Now click on the getCount link.
Since getCount is a read operation, it will return very quickly. The blockchain doesn't need to synchronize and reach consensus just to read a property of a contract.
We can see that the function returns a BigNumber that expressed in hex but is clearly 1. Keep pressing the increment() and getCount() links to increment and see the last cound.
What if all is not well?
I know that this is the simplest of smart contracts, but it's good to know how to go about debugging your code that interfaces with the smart contract. Let's set up to debug our code by creating a run profile. Click on the debug icon and then the drop-down.
Now click Add Configuration. This will bring up the launch.json configuration file in the editor and present you with a list of templates.
Pick Node.js Launch Program since the debugger is running locally(within BAS) and that where are source code is as well.
This step alone isn't sufficient for debugging. As mentioned above, the debugger runs in it's own environment and we need to simulate our module running in CloudFoundry. The run configuration needs to load the environment from the .env file and set the current directory so that it knows where to find the source files. I've created DEBUGGING.md file that has a working launch.json section that you can cut/paste into yours. Once you've done this yours might look like this.
OK, let's return to your server.js code and set a breakpoint on line 582. This is a point when handling the interact-with-last-contract link. It is checking whether an address(remember I told you to make a note) was passed in.
Also note that a new breakpoint appeared in the BREAKPOINTS section.
Now, finally we can start our module in debugger mode. Click on the green start debugging arrow.
The status bar at the bottom of the BAS window should turn orange and the debugging controls should be enabled. If you find it doesn't work, check the Debug Console for issues. Here we see that the port 8080 was already in use indicating that when we were running our module under nodejs directly, we didn't stop it. Find that terminal where it's running and do a Ctrl-C. Try debugging again.
You should get a pop-up message to open a new tab with the module. You should see 2 threads running and the restart and stop icons should be enabled. Again the bottom status bar should be orange.
Now click on the interact-with-last-contract link again. This time it should break on line 582. The line will be hi-lighted yellow to indicate it's next for execution. The THREADS and VARIABLES sections should be active and the Step-Over, Step-Into, Step-Out icons should be enabled.
For now just click on the Step-Over icon (curved arrow over dot) and see how execution would continue. You can hover over variables or expand the Local variable section to see the value of things. When you're ready to run at full speed(until the next breakpoint) then click the run icon (bar+arrow). Keep clicking links in the module or modify the browser address to change the parameters and see what happens. When you are done debugging click the stop (red square) icon (twice) and BAS status should return to blue.
What we've learned + What's next.
I hope that I've demonstrated that BAS is a more than capable tool for performing all types of development and especially Theta Blockchain Smart Contract development when tweaked to fit the need. BTP(even trial accounts) is also up to the job of running a test PrivateNet node that will allow you to quickly get your smart contracts in shape for the Theta MainNet. As of this writing the Theta MainNet 3.0 launch is less than 30 days away and promises some interesting features such as uptime mining and TFuel staking. More details can be found at ThetaToken.org.
I'll re-commit to my promise of demonstrating the very intriguing off-chain micropayments feature of the Theta blockchain in my next installment of this blog series. Stay tuned and be sure to reach out to me if you want to be kept in the loop of my efforts with SAP and Theta blockchain by dropping me an email at andrew.lunde@sap.com .
Let me know if you have and questions or issues by leaving me a question below or better yet, asking it on the SAP community.
-Andrew
| Partners: If you have a question, click here to ask it in the SAP Community . Be sure to tag it with Partnership and leave your company name in the question so that we can better assist you. |
- SAP Managed Tags:
3 Comments
