GitLocker: The Coding Marketplace

Description:

kwil 0.1.0

kwil.py

Borrows heavily from web3.py

kwil.py

What is Kwil?
Installation
Configuration

Providers
Private Key

API

helpers
high level API
low level API (Kwil.kwild API)

Fetching data
Making transactions

Usage

Connect to Kwil node
Deploy Database
Working with Actions

License

What is Kwil?
Kwil is a blockchain-based database platform, while keep being blockchain agnostic on Account.
To use Kwil.py, you need to do the following:

Create a Ethereum account
Fund the account with some required TOKEN of your kwil provider
Create database schema, through Kwil Kuneiform IDE. From there, you can get compiled schema bytes.
Deploy the database schema to the blockchain.
Create/Update data through predefined Actions.

Installation
pip install kwil

Supported python version:

3.9
3.10

Configuration
Providers
Providers are used to interact with the blockchain. They are responsible for sending and receiving RPC requests.
There are following builtin providers:

GRPCProvider - connects to a remote gRPC based server

Private Key
Kwil now support Ethereum private key to sign transaction. This key is also associated
with an Ethereum account which needed to be funded to use Kwil.
API
There are examples that shows how to use these API.
helpers

Kwil.generate_dbi(owner_addr, dataset_name)
Kwil.load_wallet(private_key)

high level API

kwil.deploy_database(payload) - deploys a new database, payload is compiled bytes of schema
kwil.get_schema(db_identifier) - returns the database schema
kwil.list_databases(OPTIONAL[owner_address]) - returns the list of databases under current account
kwil.drop_database(dataset_name) - drops the database under current account
kwil.execute_action(db_identifier, action_name, inputs) - executes the action on the database
kwil.query(db_identifier, query) - executes query(ad-hoc SQL) on the database

low level API (Kwil.kwild API)
Fetching data

Kwil.kwild.ping()
Kwil.kwild.get_config() - returns the configuration of the node
Kwil.kwild.get_schema(DBIdentifier) - returns the dataset schema info
Kwil.kwild.get_account(Adddress) - returns the account info(nonce, balance, etc)
Kwil.kwild.estimate_price(TxParams) - returns the estimated price for the transaction
Kwil.kwild.query(DBIdentifier, Query) - returns the query(ad-hoc SQL) result
Kwil.kwild.list_databases() - returns the list of databases under current account

Making transactions

Kwil.kwild.broadcast(TxParams) - broadcasts the transaction to the network

Usage
There are more examples in examples folder.
Connect to Kwil node
Kwil.py will connect to a Kwil node through a provider.
Currently, only GRPC provider is supported.
>>> from kwil import Kwil
>>> kwil = Kwil(Kwil.GRPCProvider("localhost:50051"),
Kwil.load_wallet("YOUR_ETH_PRIVATE_KEY"))
>>> kwil.is_connected()
True

Deploy Database
Assume we have our schema defined and compiled(./test_db.json). We can deploy the schema to the blockchain.
First, create a provider using Kwil.GRPCProvider.
Then, create a Kwil instance, can call deploy_database to deploy the schema to the blockchain.
Finally, call list_database to list all the databases under current account to verify it's there.
import logging

from kwil import Kwil

# assume that account has enough fund
# here we use examples/test_db.kf as our dataset schema, we'll use examples/test_db.json(compiled schema)

# create client
client = Kwil(Kwil.GRPCProvider("localhost:50051"),
Kwil.load_wallet("YOUR_ETH_PRIVATE_KEY"))

# create dataset
with open("./test_db.json", "r") as f:
schema_json = f.read()
try:
client.deploy_database(schema_json.encode("utf-8"))
except Exception as e:
logging.exception(e)

# list dataset
dbs = client.list_databases()
print("datasets after create: ", dbs)

Working with Actions
# execute an action
db_name = "testdb" # The name of the database, from the schema file
db_id = Kwil.generate_dbi(client.wallet.address, db_name)

action = "create_user"
tx_receipt = client.execute_action(db_id,
action,
# `create_user` is defined in examples/test_db.kf
[{"$id": 1, "$username": "aha", "$age": 18}])
result = tx_receipt["result"]
print("create user result: ", result)

# execute a pre-defined query through action
action = "list_users"
tx_receipt = client.execute_action(db_id, action, [])
result = tx_receipt["result"]
print("list user result:", result)

Let's extend the example above. We can call execute_action to execute an action on the database.
In our schema(examples/test_db.kf), we have
action create_user($id, $username, $age) public {
INSERT INTO users (id, username, age, wallet)
VALUES ($id, $username, $age, @caller);
}

create_user is a public action, so we can call it without any permission.
To call this action, we need to provide the dataset identifier, action name and inputs.
tx_receipt = client.execute_action(db_id,
action,
[{"$id": 1, "$username": "aha", "$age": 18}])

Here, we only create one user, the inputs is just a dict of the input parameters with values.
License
MIT