Punica TS
1. Overview
Welcome to Punica! Punica has (almost) everything you need for Ontology DApp development.
punica-tsUsage: punica-ts [options] [command] Punica CLI - The Ontology Blockchain dApp development framework Options: -v, --version output the version number -p, --project [PATH] specify a punica project directory -d, --debug print exceptions -h, --help output usage information Commands: init initialize new and empty Ontology DApp project unbox [options] download a Punica Box, a pre-built Ontology DApp project. compile [options] compile the specified contracts to avm and abi files deploy [options] deploy the specified contracts to specified chain invoke [options] invoke the list [options] list all the smartx Ontology smart contract IDE,SmartX node Ontology Blockchain private net in test mode test test Smart contracts wallet manage your ontid, account, asset tool tooling functions
2. Setting up the development environment
There are a few technical requirements before we start. Please install the following:
- Node.js 10.0.0
- Npm - installed with Node.js
Developing and Running
Execute these commands in the project's root directory:
Download
git clone 'https://github.com/OntologyCommunityDevelopers/punica-ts.git'
cd punica-ts
Install dependencies
npm install
Build
This will build the project with minimum polyfilling for better debug experience.
npm run build
You will get the packaged code under '/lib'.
3. Global install without building
npm install punica-ts -g
4. Quickstart
To use most Punica commands, you need to run them against an existing Punica project. So the first step is to create a Punica project.
4.1. Create a Project
4.1.1. Initializing a New Project
You can create a bare Punica project with no smart contracts included, use punica-ts init
command.
Once this operation is completed, you'll now have a project structure with the following items:
contracts/
: Directory for Ontology smart contracts.src/
: Directory for DApp source file.test/
: Directory for test files for testing your application and contracts.wallet/
: Directory for save Ontology wallet file.
punica-ts init --helpUsage: init [options] initialize new and empty Ontology DApp project Options: -h, --help output usage information
Note: If you not run punica cli in you project root directory, you need to use -p
or --project
option to specify your DApp project's path.
4.1.2. Creating a Box Project
You can create a bare project template, but for those just getting started, you can use Punica Boxes, which are example applications and project templates.
We'll use the ontology-tutorialtoken box, which creates a OEP4 token that can be transferred between accounts:
- Create a new directory for your Punica project:
mkdir tutorialtokencd tutorialtoken
- Download ("unbox") the MetaCoin box:
punica-ts unbox --box_name tutorialtoken
punica-ts unbox --helpUsage: unbox [options] download a Punica Box, a pre-built Ontology DApp project. Options: --box_name <BOX_NAME> specify which box to unbox -h, --help output usage information
Note:
- You can use the
punica-ts unbox --box_name <box-name>
command to download any of the other Punica Boxes. - If you not run punica cli in you project root directory, you need to use
-p
or--project
option to specify your DApp project's path.
4.2. Compiling
You can use the following command to compile your Ontology smart contracts:
punica-ts compile
If everything goes smoothly, you can find the avm
and abi
file in contracts/build
folder.
contacts ├─build │ contract.avm │ contract_abi.json
For more usage, you can use punica-ts compile --help
command.
punica-ts compile --helpUsage: compile [options] compile the specified contracts to avm and abi files Options: --contracts [CONTRACTS] specify contracts files in contracts dir -h, --help output usage information
Note: If you not run punica cli in you project root directory, you need to use -p
or --project
option to specify your DApp project's path.
4.3. Deployment
To deploy your contract, run the following:
punica-ts deploy
This will deploy your smart contract in build
directory.
A simple deployment process looks like this:
Deploying...Using network 'testNet'.Running deployment: hello_ontology.avmContract has been deployed to address 0x24ed10357c6a6506297367f29ed80065a42a4625.
For more usage, you can use punica-ts deploy --help
command.
punica-ts deploy --helpUsage: deploy [options] deploy the specified contracts to specified chain Options: --network [NETWORK] specify which network the contracts will be deployed to --avm [AVM] specify which avm file will be deployed --wallet [WALLET] specify which wallet file will be used --config [CONFIG] specify which deploy config file will be used -h, --help output usage information
Note:
- If you not run punica cli in you project root directory, you need to use
-p
or--project
option to specify your DApp project's path. - If multi
avm
file exist in yourbuild
directory, you need to use--avm
option to specify which contract you want to deploy. - If multi wallet file exist in your
wallet
directory, you may need to use--wallet
option to specify which wallet you want to use. otherwise, a random wallet file inwallet
directory will be used.
4.4. Invocation
If you want to invoke a list of function in your deployed smart contract, a convenience way is to use invoke
command.
Suppose we have an invoke config in our default-config.json
:
"invokeConfig":
To view the functions that can call:
punica-ts list
The following output we will get:
All Functions: Init Name Symbol Decimal TotalSupply BalanceOf Transfer TransferMulti Allowance TransferFrom
To run our invoke function list, run the following:
punica-ts invoke
The following output we will get:
Invoking...Using network 'testNet'.Running invocation: oep4.jsonUnlock default payer account...Please input account password: Invoking Name...Invocation was successful. Result: 546f6b656e4e616d65Invoking Symbol......
For more usage, you can use punica-ts invoke --help
command.
punica-ts invoke --helpUsage: invoke [options] invoke the Options: --network [NETWORK] specify which network the contracts will be invoked --wallet <WALLET> specify which wallet file will be used --functions <FUNCTIONS> specify which --config <CONFIG> specify which config file will be used -h, --help output usage information
Note:
- If you not run punica cli in you project root directory, you need to use
-p
or--project
option to specify your DApp project's path. - If multi wallet file exist in your
wallet
directory, you may need to use--wallet
option to specify which wallet you want to use. otherwise, a random wallet file inwallet
directory will be used.
4.5 Node
punica-ts node Ontology Blockchain private net in test mode.Please download from: https://github.com/punicasuite/solo-chain/releases
4.6. Scpm
punica-ts scpm -hUsage: scpm [options] smart contract package manager,support download and publish Options: -h, --help output usage information
4.7. Smartx
punica-ts smartx Ontology smart contract IDE - SmartX.Please go to Smartx
4.8. Test
punica-ts test -hUsage: test [options] [command] test Smart contracts Options: -h, --help output usage information Commands: template [options] generate test template file exec [options] execute the test file
4.9. Wallet
punica-ts wallet -hUsage: wallet [options] [command] manage your ontid, account, asset Options: -h, --help output usage information Commands: account manage your account asset manage your asset, transfer, balance,... ontid manage your ont_id, list or add.
4.10. Tools
punica-ts tool -hUsage: tool [options] [command] tooling functions Options: -h, --help output usage information Commands: transform transform data decryptprivatekey [options] decrypt encoded private key
4.10.1. Transformation tools
punica-ts tool transform -hUsage: transform [options] [command] transform data Options: -h, --help output usage information Commands: addresstohex [options] transform address to hex stringtohex [options] transform string to hex hexreverse [options] reverse hex string numtohex [options] transform number to NeoVM hex string generateprivatekey generate random private key
5. Example
5.1. Checkout Version
C:\tutorialtoken> punica-ts -v0.2.12
5.2. Unbox Tutorialtoken
C:\tutorialtoken> punica-ts unbox tutorialtokenDownloading...Unpacking...Unbox successful. Enjoy it!``` ### 5.3. Compile Contract ```shellC:\tutorialtoken> treeC:.├─contracts│ └─build│├─src│ └─static│ ├─css│ │ └─fonts│ ├─html│ └─js└─wallet
C:\tutorialtoken> punica-ts compileCompiling...Compiled, Thank you.
C:\tutorialtoken> treeC:.│├─contracts│ └─build│├─src│ └─static│ ├─css│ │ └─fonts│ ├─html│ └─js└─wallet
C:\tutorialtoken> tree build /FC:\TUTORIALTOKEN\BUILD oep4_token.avm oep4_token_abi.json
5.4. Deploy Smart Contract
After compile successful, you can deploy your smart contract into a Ontolog Network.
C:\tutorialtoken> punica-ts deployDeploying...Using network 'testNet'.Running deployment: oep4_token.avmContract has been deployed to address 0x24ed10357c6a6506297367f29ed80065a42a4625.
If the contract has been deployed into the current network, you will get the following output.
C:\tutorialtoken> punica-ts deployDeploying...Using network 'testNet'.Running deployment: oep4_token.avmContract is already deployed at 0x24ed10357c6a6506297367f29ed80065a42a4625
5.5. Invoke Function in Smart Contract
C:\tutorialtoken> punica-ts invokeInvoking...Using network 'testNet'.Running invocation: oep4.jsonUnlock default payer account...Please input account password: Invoking Name...Invocation was successful. Result: 546f6b656e4e616d65Invoking Symbol......