bluzelle py

Bluzelle python API

Bluzelle-py is a Python library that can be used to access the Bluzelle database service.

Setup

The Python Library is not yet published on any package manager, To install and use follow the below instructions:

$ # build the library
$ pip install "poetry==1.1.7"
$ poetry config virtualenvs.create false
$ poetry install --no-interaction --no-ansi
$ pip install .

Publishing

There is a Github action that deploys new releases (using new tags) to the PyPI packages. (required to obtain a PYPI_TOKEN from the https://pypi.org website and adding it to the Github repository secrets.)

Quick Start

To connect your instance to the Bluzelle testnet, you can:

1. mint an account by visiting https://client.sentry.testnet.private.bluzelle.com:1317/mint, which will provide a mnemonic and an address. This may take a while.

2. check your balance at https://client.sentry.testnet.private.bluzelle.com:1317/bank/balances/{address}. If your account balance is 0, mint another account until a positive ubnt balance shows

3. configure your sdk instance with the following options:

from bluzelle.sdk.bluzelle import Bluzelle

sdk = Bluzelle(
    mnemonic="space dilemma domain payment snap crouch arrange"
    " fantasy draft shaft fitness rain habit dynamic tip "
    "faith mushroom please power kick impulse logic wet cricket",
    host="https://client.sentry.testnet.private.bluzelle.com",
    port=26657,
    max_gas=100000000,
    gas_price=0.002,
)

Note: if the specified gasPrice and/or maxGas is too low, any transactions may be rejected by a validator (e.g. a transaction requires more gas than maxGas specified, or the gasPrice is too low to cover validator fees). The default suggestion for these fields above will suffice.

Note: if you want to run examples in library folder, place the codes inside a file in the root directory

Websockets vs. HTTPS

• The sdk supports both https and wss connections to the Bluzelle testnet
• For https pass the url https://client.sentry.testnet.private.bluzelle.com:26657 to the bluzelle constructor.
• For websockets pass the url wss://client.sentry.testnet.private.bluzelle.com:26657.

Note: for both version first create a sdk instance then use a asyncio loop to run the program. For more details on this see example/example.py.

Usage

sdk-hierarchy

After configuring your sdk, you will have access to various modules and their corresponding methods.

• Hierarchal format:

sdk.[module].[q or tx or field].[Method](**kwargs)

• Available Modules: db, nft, staking, bank, distribution
• Available Fields: url, address, withTransactions(fn)

Queries

Each method takes a single parameter as an object (i.e. request), and returns an object (i.e. response). To see the request and response types, see the curium/proto/[module] for queries and transactions.

• Crud module query:

response = await sdk.db.q.Read(
    QueryReadRequest(
        uuid=uuid,
        key="myKey",
    ),
    timeout=3000,
    metadata=None,
    credentials=None,
    wait_for_ready=True,
    compression=False,
)
print(reponse)

*Note: response is a Uint8Array representing the byte-encoded value that had been queried. To get the string-representation of the value, use new TextDecoder().decode(resp.value)

• Bank module query:

response = await sdk.bank.q.Balance(
    QueryBalanceRequest(
        address=sdk.wallet.address,
        denom="ubnt",
    ),
    timeout=3000,
    metadata=None,
    credentials=None,
    wait_for_ready=True,
    compression=False,
)
print(response)

Transactions

The sdk can also send transactions to the chain. Each module has a tx method to send various transaction messages.

• Crud module tx:

await sdk.db.tx.Create(
    MsgCreate(
        creator=sample_creator,
        uuid=uuid,
        key="myKey",
        value="myValue".encode("utf-8"),
        lease=Lease(hours=1),
    ),
    timeout=3000,
    metadata=None,
    credentials=None,
    wait_for_ready=True,
    compression=False,
)

*Note: the sdk is signing and sending the transaction, so the signer address must match the creator of the transaction. Otherwise, an error will be thrown

**Note: see bluzelle.codec.crud.lease_pb2 to see the Lease interface

with_transactions()

Wrap multiple messages in a single transaction.

await sdk.db.with_transactions(
    [
        MsgCreate(
            creator=sdk.wallet.address,
            uuid=uuid,
            key="firstKey",
            value="firstValue".encode("utf-8"),
            lease=Lease(hours=1),
        ),
        MsgCreate(
            creator=sdk.wallet.address,
            uuid=uuid,
            key="secondKey",
            value="firstValue".encode("utf-8"),
            lease=Lease(hours=1),
        ),
        MsgCreate(
            creator=sdk.wallet.address,
            uuid=uuid,
            key="thirdKey",
            value="firstValue".encode("utf-8"),
            lease=Lease(hours=1),
        ),
    ],
    metadata=None,
    credentials=None,
    wait_for_ready=True,
    compression=False,
    memo="optionalMemo",
)

Note: if any one of the messages fail in the function passed to withTransaction, then all messages will fail and not be committed to a block

CRUD (db) module methods

• Transactions
  • Create(kwargs)
  • Delete(kwargs)
  • DeleteAll(kwargs)
  • MultiUpdate(kwargs)
  • Rename(kwargs)
  • RenewLease(kwargs)
  • RenewLeasesAll(kwargs)
  • Update(kwargs)
  • Upsert(kwargs)
• Queries
  • Count(kwargs)
  • GetLease(kwargs)
  • GetNShortestLeases(kwargs)
  • Has(kwargs)
  • Keys(kwargs)
  • KeyValues(kwargs)
  • MyKeys(kwargs)
  • Read(kwargs)
  • Search(kwargs)

Transactions

Create(MsgCreateRequest)

Create a key-value in the database.

await sdk.db.tx.Create(
    MsgCreate(
        creator=sample_creator,
        uuid=uuid,
        key="someKeyB",
        value="someValue".encode("utf-8"),
        lease=Lease(days=1),
    ),
    timeout=3000,
    metadata=None,
    credentials=None,
    wait_for_ready=True,
    compression=False,
)

Returns: MsgCreateResponse (empty object)

MsgCreateRequest	Description	Type
creator	Signer address	str
uuid	Database identifier	str
key		str
value		bytes
metadata		bytes
lease	Key-value life-span	Lease *

*Lease(seconds= number, minutes= number, hours= number, days= number, years= number)

• Delete(MsgDeleteRequest)

Delete a key-value in the database.

await sdk.db.tx.Delete(
    MsgDelete(creator=sample_creator, uuid="myUuid", key="myKey"),
    timeout=3000,
    metadata=None,
    credentials=None,
    wait_for_ready=True,
    compression=False,
)

Returns: MsgDeleteResponse (empty object)

MsgDeleteRequest	Description	Type
creator	Signer address	str
uuid	Database identifier	str
key	Key to delete	str

• DeleteAll(MsgDeleteAllRequest)

Renew all the leases of key-values in the specified uuid.

response = await sdk.db.tx.DeleteAll(creator=sample_creator, uuid="myUuid")
print(response)

Returns: Promise=>MsgDeleteAllResponse (empty object)

MsgDeleteAllRequest	Description	Type
creator	Signer address	str
uuid	Database identifier	str

• MultiUpdate(MsgMultiUpdateRequest)

Update a set of key-values in the specified uuid.

await sdk.db.tx.MultiUpdate(
    creator=sample_creator,
    uuid="myUuid",
    keyValues=[
        MsgUpdate(
            creator=sample_creator,
            uuid="uuid",
            key="myKey-1",
            value="updatedValue-2".encode("utf-8"),
            lease=Lease(minutes=1),
        ),
        MsgUpdate(
            creator=sample_creator,
            uuid="uuid",
            key="myKey-2",
            value="updatedValue-2".encode("utf-8"),
            lease=Lease(minutes=1),
        ),
    ],
)

Returns: MsgMultiUpdateResponse (empty object)

MsgMultiUpdateRequest	Description	Type
creator	Signer address	string
uuid	Database identifier	string
keyValues	KeyValueLease(key: str, value: bytes, lease: Lease)	KeyValueLease []

• Rename(MsgRenameRequest)

Renew the lease of a key-value in the database.

await sdk.db.tx.Rename(
    MsgRename(
        creator=sample_creator, uuid="myUuid", key="existingKey", newKey="renamingKey"
    ),
    timeout=3000,
    metadata=None,
    credentials=None,
    wait_for_ready=True,
    compression=False,
)

Returns: MsgRenameResponse (empty object)

MsgRenameRequest	Description	Type
creator	Signer address	str
uuid	Database identifier	str
key	Existing key	str
newKey	New key used to rename	str

• RenewLease(MsgRenewLeaseRequest)

Renew the lease of a key-value in the database.

respons = await sdk.db.tx.RenewLease(
    MsgRenewLease(
        creator=sample_creator, uuid="myUuid", key="existingKey", lease=Lease(hours=1)
    ),
    timeout=3000,
    metadata=None,
    credentials=None,
    wait_for_ready=True,
    compression=False,
)

Returns: MsgRenewLeaseResponse (empty object)

MsgRenewLeaseRequest	Description	Type
creator	Signer address	str
uuid	Database identifier	str
key		str
lease	New life-span for key-value	Lease *

*Lease(seconds=number, minutes=number, hours=number, days=number, years=number)

• RenewLeasesAll(MsgRenewLeasesAllRequest)

Renew all the leases of key-values in the specified uuid.

await sdk.db.tx.RenewLeasesAll(
    MsgRenewLeasesAll(
        creator=sample_creator,
        uuid=uuid,
        lease=Lease(seconds=10),
    ),
    timeout=3000,
    metadata=None,
    credentials=None,
    wait_for_ready=True,
    compression=False,
)

Returns: MsgRenewLeasesAllResponse (empty object)

MsgRenewLeasesAllRequest	Description	Type
creator	Signer address	str
uuid	Database identifier	str
lease	New life-span for all key-values	Lease *

*Lease(seconds=number, minutes=number, hours=number, days=number, years=number)

• Update(MsgUpdateRequest)

Update a key-value in the database.

await sdk.db.tx.Update(
    MsgUpdate(
        creator=sample_creator,
        uuid=uuid,
        key="myKey",
        value="updatedValue".encode("utf-8"),
        lease=Lease(minutes=1),
    ),
    timeout=3000,
    metadata=None,
    credentials=None,
    wait_for_ready=True,
    compression=False,
)

Returns: MsgUpdateResponse (empty object)

MsgUpdateRequest	Description	Type
creator	Signer address	str
uuid	Database identifier	str
key		str
value	New value to update to	bytes
metadata		bytes
lease	Key-value life-span	Lease

*Lease(seconds=number, minutes=number, hours=number, days=number, years=number)

• Upsert(MsgUpsertRequest)

Upsert a key-value in the database: create a key-value if the key doesn't exist, update the key-value if the key exists

await sdk.db.tx.Upsert(
    MsgUpsert(
        creator=sample_creator,
        uuid="myUuid",
        key="keyToUpsert",
        value="valueToUpsert".encode("utf-8"),
    ),
    timeout=3000,
    metadata=None,
    credentials=None,
    wait_for_ready=True,
    compression=False,
)

Returns: MsgUpsertResponse (empty object)

MsgUpsertRequest	Description	Type
creator	Signer address	str
uuid	Database identifier	str
key		str
value		bytes
metadata		bytes
lease	Key-value life-span	Lease *

*Lease(seconds=number, minutes=number, hours=number, days=number, years=number)

Queries

• Count(QueryCountRequest)

Query the total number of key-values in the specified uuid.

await sdk.db.q.Count(
    MsgCount(uuid="myUuid"),
    timeout=3000,
    metadata=None,
    credentials=None,
    wait_for_ready=True,
    compression=False,
)

Returns: QueryCountResponse

QueryCountRequest	Description	Type
uuid	Database identifier	str

QueryCountResponse	Description	Type
count	Number of key-values in the uuid	int

• GetLease(QueryGetLeaseRequest)

Get the remaining lease time of a key-value.

response = await sdk.db.q.GetLease(
    QueryGetLeaseRequest(
        uuid=uuid,
        key="myKey",
    ),
    timeout=3000,
    metadata=None,
    credentials=None,
    wait_for_ready=True,
    compression=False,
)

Returns: QueryGetLeaseResponse

QueryGetLeaseRequest	Description	Type
uuid	Database identifier	str
key		str

QueryGetLeaseResponse	Description	Type
seconds	Remaining lease time of key-value	number

• GetNShortestLeases(QueryGetNShortestLeasesRequest)

Get the remaining lease time of a n key-values.

response = await sdk.db.q.GetNShortestLeases(
    QueryGetNShortestLeasesRequest(
        uuid=uuid,
        num=5,
    ),
    timeout=3000,
    metadata=None,
    credentials=None,
    wait_for_ready=True,
    compression=False,
)

Returns: QueryGetNShortestLeasesResponse

QueryGetNShortestLeasesRequest	Description	Type
uuid	Database identifier	str
num	Number of keyLeases to return	int

QueryGetNShortestLeasesResponse	Description	Type
keyLeases	KeyLease(key=string, seconds=number)	list(KeyLease)

• Has(QueryHasRequest)

Check if a key exists in the specified uuid.

await sdk.db.q.Has(
  MsgHas((uuid = "myUuid"), (key = "myKey")),
  (timeout = 3000),
  (metadata = None),
  (credentials = None),
  (wait_for_ready = True),
  (compression = False)
);

Returns: QueryHasResponse

QueryHasRequest	Description	Type
uuid	Database identifier	str
key		str

QueryHasResponse	Description	Type
has	true if key exists in uuid; false otherwise	bool

• Keys(QueryKeysRequest}

Read the complete set of keys in the specified uuid. ###hhio

await sdk.db.q.Keys(
    MsgKeys(uuid="myUuid", pagination={"start": "key-a", "limit": 50}),
    timeout=3000,
    metadata=None,
    credentials=None,
    wait_for_ready=True,
    compression=False,
)

Returns: QueryKeysResponse

QueryKeysRequest	Description	Type
uuid	Database identifier	str
pagination (optional)	PagingRequest(startKey=string, limit=Long)	PagingRequest

QueryKeysResponse	Description	Type
keys		list(str)
pagination (optional)	PagingResponse {nextKey: string, total: Long}	PagingResponse

• KeyValues(QueryKeyValuesRequest)

Read the complete set of key-values in the specified uuid.

response = await sdk.db.q.KeyValues(
    QueryKeyValuesRequest(uuid=uuid),
    timeout=3000,
    metadata=None,
    credentials=None,
    wait_for_ready=True,
    compression=False,
)

Returns: QueryKeyValuesResponse

QueryKeyValuesRequest	Description	Type
uuid	Database identifier	str
pagination (optional)	PagingRequest {startKey: string, limit: Long}	PagingRequest

QueryKeyValuesResponse	Description	Type
keyValues	KeyValue {key: string, value: Uint8Array}	list(KeyValue)
pagination (optional)	PagingResponse {nextKey: string, total: Long}	PagingResponse

• MyKeys(QueryMyKeysRequest)

Read the complete set of keys by address in the specified uuid. ###hhio

await sdk.db.q.Keys(
  MsgKeys((uuid = "myUuid"), (address = sample_creator)),
  (timeout = 3000),
  (metadata = None),
  (credentials = None),
  (wait_for_ready = True),
  (compression = False)
);

Returns: QueryMyKeysResponse

QueryMyKeysRequest	Description	Type
uuid	Database identifier	str
address	Bluzelle address	str
pagination (optional)	PagingRequest {startKey: string, limit: Long}	PagingRequest

QueryMyKeysResponse	Description	Type
keys		list(string)
pagination (optional)	PagingResponse {nextKey: string, total: Long}	PagingResponse

• Read(QueryReadRequest)

Read a value from the database.

response = await sdk.db.q.Read(
    QueryReadRequest(
        uuid=uuid,
        key="myKey",
    ),
    timeout=3000,
    metadata=None,
    credentials=None,
    wait_for_ready=True,
    compression=False,
)

Returns: QueryReadResponse

QueryReadRequest	Description	Type
uuid	Database identifier	str
key		str

QueryReadResponse	Description	Type
value		bytes

• Search(QuerySearchRequest)

Search by key in the specified uuid.

response = await sdk.db.q.Search(
    QuerySearchRequest(
        uuid=uuid,
        searchString="s",
    ),
    timeout=3000,
    metadata=None,
    credentials=None,
    wait_for_ready=True,
    compression=False,
)

Returns: QuerySearchResponse

QuerySearchRequest	Description	Type
uuid	Database identifier	str
searchString	query for keys that start with or match searchString	str
pagination (optional)	{startKey: string, limit: Long}	PagingRequest

QuerySearchResponse	Description	Type
keyValues	KeyValue {key: string, value: Uint8Array}	list(KeyValue)
pagination (optional)	{nextKey: string, total: Long}	PagingResponse