Skip to content

punicasuite/punica-ts

master
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 


Punica TS

1. Overview

Welcome to Punica! Punica has (almost) everything you need for Ontology DApp development.

punica-ts
Usage: 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 function list in default-config or specify config.
  list [options]        list all the function in default-config or specified config.
  smartx                Ontology smart contract IDE,SmartX (http://smartx.ont.io/)
  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:

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 --help
Usage: 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 tutorialtoken
cd tutorialtoken
  • Download ("unbox") the MetaCoin box:
punica-ts unbox --box_name tutorialtoken
punica-ts unbox --help
Usage: 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 --help
Usage: 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.avm
Contract has been deployed to address 0x24ed10357c6a6506297367f29ed80065a42a4625.

For more usage, you can use punica-ts deploy --help command.

punica-ts deploy --help
Usage: 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 your build 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 in wallet 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":{
    "abi": "oep4_token_abi.json",
    "defaultPayer": "ANH5bHrrt111XwNEnuPZj6u95Dd6u7G4D6",
    "gasPrice": 0,
    "gasLimit": 21000000,
    "functions": [
        {   
	    "name": "Name",
            "params": {},
            "signers": {},
            "preExec": true
        },
	{
            "name": "Symbol",
            "params": {},
            "signers": {},
            "preExec": true
        },
	{
            "name": "Decimal",
            "params": {},
            "signers": {},
            "preExec": true
        },
        {
	    "name": "TotalSupply",
            "params": {},
            "signers": {},
            "preExec": true
        },
        {
	    "name":"BalanceOf",
            "params": {
                "account": "ByteArray:ANH5bHrrt111XwNEnuPZj6u95Dd6u7G4D6"
            },
            "signers": {},
            "preExec": true
        },
        {
	    "name": "Transfer",
            "params": {
                "from_acct": "ByteArray:ANH5bHrrt111XwNEnuPZj6u95Dd6u7G4D6",
                "to_acct": "ByteArray:AazEvfQPcQ2GEFFPLF1ZLwQ7K5jDn81hve",
                "amount": 1
            },
            "signers": {
                "m": 1,
                "signer": ["ANH5bHrrt111XwNEnuPZj6u95Dd6u7G4D6"]
            },
            "preExec": false
        },
        {
	    "name": "TransferMulti",
            "params": {
                "args": [
                    {
                        "from": "ByteArray:ANH5bHrrt111XwNEnuPZj6u95Dd6u7G4D6",
                        "to": "ByteArray:AazEvfQPcQ2GEFFPLF1ZLwQ7K5jDn81hve",
                        "amount": 1
                    },
                    {
                        "from": "ByteArray:AazEvfQPcQ2GEFFPLF1ZLwQ7K5jDn81hve",
                        "to": "ByteArray:Ad4H6AB3iY7gBGNukgBLgLiB6p3v627gz1",
                        "amount": 2
                    }
                ]
            },
            "signers": {
                "m": 1,
                "signer": ["ANH5bHrrt111XwNEnuPZj6u95Dd6u7G4D6", "AazEvfQPcQ2GEFFPLF1ZLwQ7K5jDn81hve"]
            },
            "payer": "ANH5bHrrt111XwNEnuPZj6u95Dd6u7G4D6",
            "preExec": false
        },
        {
	    "name": "Allowance",
            "params": {
                "owner": "ByteArray:ANH5bHrrt111XwNEnuPZj6u95Dd6u7G4D6",
                "spender": "ByteArray:AazEvfQPcQ2GEFFPLF1ZLwQ7K5jDn81hve"
            },
            "signers": {
                "m": 1,
                "signer": ["ANH5bHrrt111XwNEnuPZj6u95Dd6u7G4D6"]
            },
            "preExec": false
        },
        {
	    "name": "TransferFrom",
            "params": {
                "sender": "ByteArray:AazEvfQPcQ2GEFFPLF1ZLwQ7K5jDn81hve",
                "from_acct": "ByteArray:ANH5bHrrt111XwNEnuPZj6u95Dd6u7G4D6",
                "to_acct": "ByteArray:Ad4H6AB3iY7gBGNukgBLgLiB6p3v627gz1",
                "amount": 1
            },
            "signers": {
                "m": 1,
                "signer": ["ANH5bHrrt111XwNEnuPZj6u95Dd6u7G4D6"]
            },
            "preExec": false
        },
        {
	    "name": "Init",
            "params": {},
            "signers": {},
            "preExec": true
        }
    ]
}

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.json
Unlock default payer account...
Please input account password: 
Invoking Name...
Invocation was successful. Result: 546f6b656e4e616d65
Invoking Symbol......

For more usage, you can use punica-ts invoke --help command.

punica-ts invoke --help
Usage: invoke [options]

invoke the function list in default-config or specify config.

Options:
  --network [NETWORK]      specify which network the contracts will be invoked
  --wallet <WALLET>        specify which wallet file will be used
  --functions <FUNCTIONS>  specify which function will be executed
  --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 in wallet 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 -h
Usage: 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 for debugging smart contracts: http://smartx.ont.io/#/

4.8. Test

punica-ts test -h
Usage: 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 -h
Usage: 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 -h
Usage: 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 -h
Usage: 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 -v
0.2.12

5.2. Unbox Tutorialtoken

C:\tutorialtoken> punica-ts unbox tutorialtoken
Downloading...
Unpacking...
Unbox successful. Enjoy it!```

### 5.3. Compile Contract

```shell
C:\tutorialtoken> tree
C:.
├─contracts
│     └─build
│
├─src
│  └─static
│      ├─css
│      │  └─fonts
│      ├─html
│      └─js
└─wallet
C:\tutorialtoken> punica-ts compile
Compiling...
Compiled, Thank you.
C:\tutorialtoken> tree
C:.
│
├─contracts
│     └─build
│
├─src
│  └─static
│      ├─css
│      │  └─fonts
│      ├─html
│      └─js
└─wallet
C:\tutorialtoken> tree build /F
C:\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 deploy
Deploying...
Using network 'testNet'.
Running deployment: oep4_token.avm
Contract 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 deploy
Deploying...
Using network 'testNet'.
Running deployment: oep4_token.avm
Contract is already deployed at 0x24ed10357c6a6506297367f29ed80065a42a4625

5.5. Invoke Function in Smart Contract

C:\tutorialtoken> punica-ts invoke
Invoking...
Using network 'testNet'.
Running invocation: oep4.json
Unlock default payer account...
Please input account password: 
Invoking Name...
Invocation was successful. Result: 546f6b656e4e616d65
Invoking Symbol......

About

Ontology Blockchain dApp development framework

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •