Metadata-Version: 2.1
Name: punica
Version: 0.0.4
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)
- [Invocation](#invocation)

<!-- /TOC -->

## 1. Overview

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

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

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

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

**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 'test'.

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

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

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

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

