Metadata-Version: 2.1
Name: punica
Version: 0.0.5
Summary: Ontology DApp Development Framework
Home-page: https://github.com/ontio-community/punica-python
Author: NashMiao
Author-email: wdx7266@outlook.com
Maintainer: NashMiao
Maintainer-email: wdx7266@outlook.com
License: MIT
Platform: UNKNOWN
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Requires-Python: >=3.7,<4
Description-Content-Type: text/markdown
Requires-Dist: Click
Requires-Dist: GitPython
Requires-Dist: punica-neo-boa
Requires-Dist: ontology-python-sdk

# punica-python

<!-- TOC -->

- [1. Overview](#1-overview)
- [2. Setting up the development environment](#2-setting-up-the-development-environment)
- [3. Install](#3-install)
- [4. Quickstart](#4-quickstart)
    - [4.1. Creating a Box Project](#41-creating-a-box-project)
    - [4.2. Initializing a New Project](#42-initializing-a-new-project)
    - [4.3. Compiling](#43-compiling)
    - [4.4. Deployment](#44-deployment)
    - [4.5. Invocation](#45-invocation)

<!-- /TOC -->

## 1. Overview

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

```shell
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](https://www.python.org/downloads/release/python-370/)
- [Git](https://git-scm.com/)

## 3. Install

```shell
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](https://github.com/wdx7266/ontology-tutorialtoken), which creates a OEP4 token that can be transferred between accounts:

- Create a new directory for your Punica project:

```shell
mkdir tutorialtoken
cd tutorialtoken
```

- Download ("unbox") the MetaCoin box:

```shell
punica unbox ontology-tutorialtoken
```

```shell
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.

```shell
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:

```shell
punica compile
```

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

```shell
├─build
│      contract.avm
│      contract_abi.json
```

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

```shell
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:

```shell
punica deploy
```

This will deploy your smart contract in `bin` directory.

A simple deployment process looks like this:

```shell
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.

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

  Deploys the specified contracts to specified chain.

Options:
  --password TEXT
  --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`:

```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:

```shell
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.

```shell
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.

