NEM2 Advent Calendar Article: Catapult: Disposable Smart Contracts
Hello dear NEMbers,
This article should give you an idea of how to create disposable smart contracts with Catapult in your software applications and is written within the scope of the NEM2 Advent Calendar run by our lovely Japan community!
As you may well know, Catapult has been released in its Release Candidate version of which you can find the source code at Github. Following this release, the NEM Foundation Technology Department has been working on tooling for a Public Testnet for Catapult.
Network Environment
We will be using a set of building blocks of the Catapult technology which include namespaces, mosaics (assets), transactions, blocks, accounts, metadata and restrictions. As a matter of fact, writing your first Smart Contract with Catapult is easy and simple as will demonstrate this short case study.
In the aim of facilitating the integration and execute our smart contracts on the Public Testnet for Catapult, we will be using the TypeScript SDK for Catapult. Adding to it, you can use the Explorer client application to verify the data being published / created with our smart contracts.
Impatient? Have a look at the source code of the nem2-smart-contracts software at Github.
You will need nem.xem mosaics to pay fees
Should you be using a new account which does not own anynem.xem, feel free to use our online faucet application: http://faucet-01.nemtech.network. This software will send a small amount ofnem.xemmosaics to your account which should cover more than the required fees - fees on the Public Testnet for Catapult are of, approximately0.03 nem.xemfor a transfer transaction.
nem.xemnow following this link
Into some code
In the optic of minimizing the required time-to-delivery of this case study application, we will be using clime to create a command line tool as the outcome. This tool will let us focus on our disposable smart contracts scope.
The first step of this case study will be to install the nem2-smart-contracts software with your terminal as well as compile the software package so that it can be used on your local machine. This step is simple enough and you can do it using your terminal:
Preparing your Environment
$ git clone https://github.com/evias/nem2-smart-contracts
$ cd nem2-smart-contracts && npm install && npm run build
We can now use the nem2-smart-contracts package to create disposable smart contracts. As you will see, in this package are a few disposable smart contracts that can be executed out-of-the-box. We will go through each of them during this article.
Smart Contract #1: Creation of Named Assets
This first disposable smart contract will permit us to create a mosaic (asset), then register a namespace and publish an alias for the created asset. This smart contract can be used to create named assets with Catapult.
This smart contracts consists of executing the following steps - atomically:
- Create and configure an asset using Mosaics.
- Register a namespace that expires after one year.
- Link the created namespace to the created asset.
These steps will be executed in one aggregate transaction that will be broadcast to the Public Testnet for Catapult.
Particularity: The particularity about this smart contract is that after its execution, it is possible to use your newly created asset by referring to it by its name.
This smart contract can be executed multiple times to create multiple assets. Please, make sure to backup the account private key that is used to generate the owner account.
$ ./nem2-smart-contracts AssetCreation --name organization.asset --supply 1500000
Smart Contract Inputs
This disposable smart contract accepts following inputs:
Parameter Description Example --name Sets a friendly name --name evias.asset--divisibility Sets the divisibility (number of decimal places) --divisibility 2--supply Sets the initial supply (number of units) --supply 10--flags Set mosaic flags --flags SupplyMutable
Smart Contract #2: Escrow of assets
This second disposable smart contract will permit us to perform a decentralized swap of assets. This smart contract can be used to perform a decentralized swap of assets between two accounts and using two different mosaics.
This smart contracts consists of executing the following steps:
- Create the transfer of mosaic M1 from Alice to Bob.
- Create the transfer of mosaic M2 from Bob to Alice.
These steps will be executed in one aggregate transaction that will be broadcast to the Public Testnet for Catapult.
Particularity: The particularity about this smart contract is that it locks funds for both accounts until both parties have confirmed the intention of swap.
This smart contract can be executed multiple times to escrow funds with different parties. Escrow contracts expire after 48 hours if one of the two involved parties does not confirm the transaction.
$ ./nem2-smart-contracts AssetEscrow --asset1 10 nem.xem --asset2 1 theater.ticket --taker 4574367DCF64AE285AEA5BA69B9EE7F507DB43FCA3CBB45C201DAC9639D4F3B4
This disposable smart contract accepts following inputs:
Parameter Description Example --asset1 Sets the left-hand asset --asset1 10 nem.xem--asset2 Sets the right-hand asset --asset2 1 theater.ticket--taker Sets the right-hand (taker) account public key --taker 4574...F3B4--lock (Optional) Sets the mosaic that is used for spam protection --lock 10 nem.xem
Smart Contract #3: Request mosaic from a friend
This third disposable smart contract will permit us to request mosaic from a friend. This smart contract can be used to request assets from other accounts.
This smart contracts consists of executing the following steps:
- Create a transfer transaction from your friend to your address.
- Await your friend’s confirmation for the request.
These steps will be executed in one aggregate transaction that will be broadcast to the Public Testnet for Catapult.
Particularity: The particularity about this smart contract is that it lets you request any mosaic from any account. In fact, this permits for your to create a transaction which your friend has to confirm. In this way, it is possible to request the fees needed for a transaction, as a first step of any business layer logic that requires fees to be paid.
This smart contract can be executed multiple times to send multiple requests. The issuer account must hold network currency as it needs to send a hash lock transaction (SPAM protection) first.
$ ./nem2-smart-contracts AssetRequest --asset 10 nem.xem --from TDNNBX7B44CJZFQGU7XAG62SQSJQOWY4P5KACYPD
This disposable smart contract accepts following inputs:
Parameter Description Example --asset The asset to request (amount and mosaic) --asset 10 nem.xem--from Sets the recipient of the request --from TDNNBX7B44CJZFQGU7XAG62SQSJQOWY4P5KACYPD--lock (Optional) Sets the mosaic that is used for spam protection --lock 10 nem.xem
Smart Contract #4: Sending Partial Transaction Signatures
This last disposable smart contract will permit us send co-signature transactions for partial transactions. This smart contract can be used to complete partial transactions when they are still missing co-signatures.
This smart contracts consists of executing the following steps:
- Read unsigned (partial) transactions
- Issue co-signature transaction for a parent aggregate bonded transaction
These steps will be executed in step that will be broadcast to the Public Testnet for Catapult.
Particularity: The particularity about this smart contract is that it lets you send co-signatures for multiple parties involved in a partial transaction (aggregate bonded). This smart contract can be used whenever a partial transaction is a missing a co-signature from one of your accounts.
This smart contract can be executed multiple times to send multiple co-signatures. When there is no transaction missing co-signatures, the contract will simply abort.
$ ./nem2-smart-contracts PartialCosignature --hash B38C791028F168FFC5F2DBDD3B89237BF4ABC7FCABF72C4A0B45A17F7AFB07C1
This disposable smart contract accepts following inputs:
Parameter Description Example --hash Sets the aggregate bonded transaction hash --hash B38C7910...07C1
One-Time Transparent Execution
What all these smart contracts have in common is that they can be executed at any given time, over and over. Their execution is guaranteed to either succeed and be verifiable - or cancel all actions and leave 0 traces due to the failure of one or more of the steps executed by said smart contract.
This type of one-time execution of pre-configured disposable smart contracts permits to execute a lot of different actions affecting the state on-chain. Actions, which are either going to succeed or fail altogether. These smart contracts are said to be atomic because the execution of the actions depends on the validity of all actions executed one after the other.
Assemble the Building Blocks!
With this ground stone laid on how to create disposable smart contracts with Catapult, it is now time that we get more useful contract ideas that can then be integrated to this software package. You can basically think about any suite of transactions to execute in one contract ; as long as your idea can be executed using out-of-the-box features of Catapult.
As a few ideas that came across my mind during the edition of this article are the following disposable smart contracts:
- Transfer the ownership of an account
- Create multi-level account hierarchies
- Create named accounts
- Whitelist/Blacklist usage of an asset (restrictions)
- Feel free to add to this list!
The main principle with the nem2-smart-contracts package is that a contract executes by wrapping all configured transactions inside an aggregate transactions. This means that any list of valid transactions can effectively be wrapped as a disposable smart contract.
Using Catapult building blocks such as namespaces, mosaics (assets), transactions, blocks, accounts, metadata and restrictions - it is possible to cover business logic that was previously not even executable within multi-signature transactions.
With aggregate transactions, in fact, Catapult adds flexibility, extendability and atomicity to an already well-garnished feature set. Don’t miss out on these disposable smart contracts - Send us a Disposable Smart Contract Proposal in the form of an issue at Github.
Source code reference
Because, what would a tech article look like without a source code reference, right?
Package Github
nem2-smart-contracts
Contracts Source Code
Source code for the AssetCreation one-time smart contract
Source code for the AssetEscrow one-time smart contract
Source code for the AssetRequest one-time smart contract
Source code for the PartialCosignature one-time smart contract
Kernel Software
Source code for the Contract abstract class
Usage of the nem2-hd-wallets second layer library
Source code for the TransactionFactory class
Source code for the TransactionSigner class
Thank you #NEM
Thank you for reading, Nembers. I hope you enjoyed this advent calendar article!
As usual, I am looking forward to your thoughts, feedback and/or request proposals.
See you #soon!