punica 0.0.6

Ontology DApp Development Framework

punica-python

• 1. Overview
• 2. Setting up the development environment
• 3. Install
• 4. Quickstart
  • 4.1. Creating a Box Project
  • 4.2. Initializing a New Project
  • 4.3. Compiling
  • 4.4. Deployment
  • 4.5. Invocation
• Example
  • Unbox Tutorialtoken
  • Compile Contract
  • Deploy

1. Overview

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

punica
Usage: punica [OPTIONS] COMMAND [ARGS]...

Options:
  -p, --project PATH  Specify a punica project directory.
  -h, --help          Show this message and exit.

Commands:
  compile  Compile the specified contracts to avm and abi file.
  deploy   Deploys the specified contracts to specified chain.
  init     Initialize new and empty Ontology DApp project.
  invoke   Invoke the function list in punica-config.
  unbox    Download a Punica Box, a pre-built Ontology DApp project.

2. Setting up the development environment

There are a few technical requirements before we start. Please install the following:

• Python 3.7
• Git

3. Install

pip install punica

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. 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 unbox ontology-tutorialtoken

punica unbox --help
Usage: punica unbox [OPTIONS] BOX_NAME

  Download a Punica Box, a pre-built Ontology DApp project.

Options:
  -h, --help  Show this message and exit.

Note:

• You can use the punica unbox <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. Initializing a New Project

You can create a bare Punica project with no smart contracts included, use punica 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 init --help
Usage: punica init [OPTIONS]

  Initialize new and empty Ontology DApp project.

Options:
  -h, --help  Show this message and exit.

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. Compiling

You can use the following command to compile your Ontology smart contracts:

punica compile

If everything goes smoothly, you can find the avm and abi file in build folder.

├─build
│      contract.avm
│      contract_abi.json

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

punica compile --help
Usage: punica compile [OPTIONS] CONTRACT_NAME

  Compile the specified contracts to avm and abi file.

Options:
  --avm TEXT  Only generate avm file flag.
  --abi TEXT  Only generate abi file flag.
  -h, --help  Show this message and exit.

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.4. Deployment

To deploy your contract, run the following:

punica deploy

This will deploy your smart contract in bin directory.

A simple deployment process looks like this:

Using network 'testNet'.

Running deployment: oep4.avm
	Deploying...
	... 0x0131c56b6a00527ac46a51527ac46a00c3044e616d659c6409006593096c7566
	Deploy to: 0xf9f47e6a80482eb1c8831789f46dbc5a4f606222
Deploy successful to network...
	... 0xc08a440a7f93cc7229fee15b55455fac51ec15153753303bd252c710547ecb62
Enjoy your contract:)

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

punica deploy --help
Usage: punica deploy [OPTIONS]

  Deploys the specified contracts to specified chain.

Options:
  --network TEXT   Specify which network the contract will be deployed.
  --avm TEXT       Specify which avm file will be deployed.
  --wallet TEXT    Specify which wallet file will be used.
  -h, --help       Show this message and exit.

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 bin 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.5. Invocation

If you want to invoke a list of function in your deployed smart contract, a convenience way is to use Invoke command.

Support we have an invoke config in our punica-config.json:

"invokeConfig":{
    "abi":"oep4.json",
    "defaultPayer":"ANH5bHrrt111XwNEnuPZj6u95Dd6u7G4D6",
    "gasPrice": 500,
    "gasLimit": 21000000,
    "Functions":{
      "Name":{
        "params":[],
        "signers":[]
      },
      "Symbol":{
        "params":[],
        "signers":[]
      },
      "Decimal":{
        "params":[],
        "signers":[]
      },
      "TotalSupply":{
        "params":[],
        "signers":[]
      },
      "BalanceOf":{
        "params":["ANH5bHrrt111XwNEnuPZj6u95Dd6u7G4D6"],
        "signers":[]
      },
      "Transfer":{
        "params":["ANH5bHrrt111XwNEnuPZj6u95Dd6u7G4D6","AazEvfQPcQ2GEFFPLF1ZLwQ7K5jDn81hve",1],
        "signers":["ANH5bHrrt111XwNEnuPZj6u95Dd6u7G4D6"],
        "payer":"ANH5bHrrt111XwNEnuPZj6u95Dd6u7G4D6"
      },
      "TransferMulti":{
        "params":[["ANH5bHrrt111XwNEnuPZj6u95Dd6u7G4D6", "AazEvfQPcQ2GEFFPLF1ZLwQ7K5jDn81hve", 1], ["AazEvfQPcQ2GEFFPLF1ZLwQ7K5jDn81hve", "Ad4H6AB3iY7gBGNukgBLgLiB6p3v627gz1", 2]],
        "signers":["ANH5bHrrt111XwNEnuPZj6u95Dd6u7G4D6","AazEvfQPcQ2GEFFPLF1ZLwQ7K5jDn81hve"],
        "payer":"ANH5bHrrt111XwNEnuPZj6u95Dd6u7G4D6"
      },
      "Allowance":{
        "params":["ANH5bHrrt111XwNEnuPZj6u95Dd6u7G4D6","AazEvfQPcQ2GEFFPLF1ZLwQ7K5jDn81hve"],
        "signers":["ANH5bHrrt111XwNEnuPZj6u95Dd6u7G4D6"]
      },
      "TransferFrom":{
        "params":["AazEvfQPcQ2GEFFPLF1ZLwQ7K5jDn81hve","ANH5bHrrt111XwNEnuPZj6u95Dd6u7G4D6","Ad4H6AB3iY7gBGNukgBLgLiB6p3v627gz1",1],
        "signers":["ANH5bHrrt111XwNEnuPZj6u95Dd6u7G4D6"]
      }
    }
}

To run our invoke function list, run the following:

punica invoke

The following output we will get:

Running invocation: oep4.json
Using network 'testNet'.

Unlock default payer account...
	Unlock account: ANH5bHrrt111XwNEnuPZj6u95Dd6u7G4D6
    Please input account password: 
	Unlock successful...
Invoking Name...
	Invoke successful...
		... Invoke result: 546f6b656e4e616d65
Invoking Symbol...
	Invoke successful...
		... Invoke result: 53796d626f6c
Invoking Decimal...
	Invoke successful...
		... Invoke result: 08
Invoking TotalSupply...
	Invoke successful...
		... Invoke result: 00008a5d78456301
Invoking BalanceOf...
	Invoke successful...
		... Invoke result: e7fd895d78456301
Invoking Transfer...
Unlock signers account...
	Unlock account: ANH5bHrrt111XwNEnuPZj6u95Dd6u7G4D6
    Please input account password: 
	Unlock successful...
	Invoke successful...
		... txHash: 0xeaaa80394ee8d0c0229787ba811916432a0741833d2beaf60a5a80dbdfb9a45d
Invoking TransferMulti...
Unlock signers account...
	Unlock account: AazEvfQPcQ2GEFFPLF1ZLwQ7K5jDn81hve
    Please input account password: 
	Unlock successful...
	Invoke successful...
		... txHash: 0xc6c4fc178b3598ad329986782d8c6ffdc4858ae208d48c7ce429532cec39fc68
Invoking Allowance...
Unlock signers account...
	Unlock account: ANH5bHrrt111XwNEnuPZj6u95Dd6u7G4D6
    Please input account password: 
	Unlock successful...
	Invoke successful...
		... txHash: 0xc8f0433e9042ed45fbac9576d8ff778598db7ac1d563e51b499b047bdd58dd01
Invoking TransferFrom...
Unlock signers account...
	Unlock account: ANH5bHrrt111XwNEnuPZj6u95Dd6u7G4D6
    Please input account password: 
	Unlock successful...
	Invoke successful...
		... txHash: 0x7cb1c72b4e803a5ab80d9fcf96445392ed391cb68a23fa8459d4c6899f90611d

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

punica invoke --help
Usage: punica invoke [OPTIONS]

  Invoke the function list in punica-config.

Options:
  --network TEXT  Specify which network the contract will be deployed.
  --wallet TEXT   Specify which wallet file will be used.
  -h, --help      Show this message and exit.

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.

Example

Unbox Tutorialtoken

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

Compile Contract

C:\tutorialtoken> tree
C:.
├─contracts
├─src
│  └─static
│      ├─css
│      │  └─fonts
│      ├─html
│      └─js
└─wallet

C:\tutorialtoken> punica compile
Compile...
        Compile oep4_token.py...
        Generate abi file and avm file successful...
        Enjoy your contract:)
Now we are finished :)

C:\tutorialtoken> tree
C:.
├─build
├─contracts
├─src
│  └─static
│      ├─css
│      │  └─fonts
│      ├─html
│      └─js
└─wallet

C:\tutorialtoken> tree build /F
C:\TUTORIALTOKEN\BUILD
    oep4_token.avm
    oep4_token_abi.json

Deploy

If the contract has been deployed into the current network, you will get the following output.

C:\tutorialtoken> punica deploy
Using network 'testNet'.

Running deployment: oep4_token.avm
        Deploy failed...
        Contract has been deployed...
        Contract address is 0xcb9f3b7c6fb1cf2c13a40637c189bdd066a272b4...
Enjoy your contract:)