sdk-js is a JavaScript library that can be used to access the Bluzelle database service.

Setup

1) sudo apt update

2) curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash

3) export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

4) exec "$SHELL"

5) nvm install 14 

6) nvm use 14

sdk-js Installation

yarn add @bluzelle/sdk-js
or
npm install @bluzelle/sdk-js

Quick Start

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

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.
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
configure your sdk instance with the following options:

import {bluzelle} from '@bluzelle/sdk-js'

const sdk = await bluzelle({
        mnemonic: mnemonic_from_mint_endpoint, 
        url: "wss://client.sentry.testnet.private.bluzelle.com:26657",
        maxGas: 100000000, 
        gasPrice:  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.

Websockets vs. HTTPS

Currently the sdk supports both websocket and https connections to the Bluzelle testnet
Use websockets (wss://client.sentry.testnet.private.bluzelle.com:26657) for greater performance
For https pass the url https://client.sentry.testnet.private.bluzelle.com:26657 to the bluzelle constructor

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]({...request fields})

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:

sdk.db.q.Read({
	uuid: 'myUuid', 				// Read takes a QueryReadRequest object
	key: 'myKey'		 
})
.then(resp => resp.value) 	

// returns a promise of a QueryReadResponse object*

*Note: resp.value 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:

sdk.bank.q.Balance({
	address: sdk.bank.address, 	// you can access your sdk's bluzelle address
	denom: 'ubnt'
})

Transactions

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

Crud module tx:

sdk.db.tx.Create({					// takes a MsgCreateRequest object
     creator: sdk.db.address,     			// the creator of the transaction should always be the sender's address*
     uuid: 'uuid',	
     key: 'myKey',
     value: new TextEncoder().encode('myValue'),	// values are stored as byte arrays 
     metadata: new Uint8Array(),			
     lease: {days: 0, seconds: 0, years: 0, hours: 1, minutes: 0} // Lease object to specify lifespan of key-value**
})
 
 // returns a promise of a MsgCreateResponse, which in this case is an empty object

*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 codec/crud/lease.ts to see the Lease interface

Bank module tx:

sdk.bank.tx.Send({
	amount: [{
		denom: 'ubnt',
		amount: '300'
	}], 
	fromAddress: sdk.bank.address, 
	toAddress: [some_bluzelle_address]
})

Note: IDEs should recognize the types and auto-fill the sdk module hierarchy, and the corresponding fields for the request and response objects for each method: IntelliJ, VS, WebStorm, PhpStorm, etc.

withTransactions(() => {...})

Wrap multiple messages in a single transaction.

sdk.db.withTransactions(() => {
  sdk.db.tx.Create({
    creator: sdk.db.address,
    uuid: 'uuid',
    key: 'firstKey',
    value: new TextEncoder().encode('firstValue'),
    metadata: new Uint8Array(),
    lease: {days: 0, seconds: 0, years: 0, hours: 1, minutes: 0}
  });
  sdk.db.tx.Create({
    creator: sdk.db.address,
    uuid: 'uuid',
    key: 'secondKey',
    value: new TextEncoder().encode('secondValue'),
    metadata: new Uint8Array(),
    lease: {days: 0, seconds: 0, years: 0, hours: 1, minutes: 0}
  });
  sdk.db.tx.RenewLeasesAll({
    creator: sdk.db.address,
    uuid: 'uuid',
    lease: {days: 0, seconds: 0, years: 0, hours: 3, minutes: 0}
  });
}, {memo: 'someMemo'});

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({...})
- Delete({...})
- DeleteAll({...})
- MultiUpdate({...})
- Rename({...})
- RenewLease({...})
- RenewLeasesAll({...})
- Update({...})
- Upsert({...})
Queries
- Count({...})
- GetLease({...})
- GetNShortestLeases({...})
- Has({...})
- Keys({...})
- KeyValues({...})
- MyKeys({...})
- Read({...})
- Search({...})

Transactions

Create(MsgCreateRequest)

Create a key-value in the database.

const createResp = await sdk.db.tx.Create({
  creator: sdk.db.address,
  uuid: 'myUuid',
  key: 'myKey',
  value: new TextEncoder().encode('myValue'),
  metadata: new Uint8Array(),
  lease: {days: 0, seconds: 0, years: 0, hours: 1, minutes: 0}
})

.....

sdk.db.tx.Create({
  creator: sdk.db.address,
  uuid: 'myUuid',
  key: 'secondKey',
  value: new TextEncoder().encode('secondValue'),
  metadata: new Uint8Array(),
  lease: {days: 0, seconds: 0, years: 0, hours: 1, minutes: 0}
})
	.then(resp => {...})
	.catch(err => {...})

Returns: Promise=>MsgCreateResponse (empty object)

MsgCreateRequest	Description	Type
creator	Signer address	string
uuid	Database identifier	string
key		string
value		Uint8Array
metadata		Uint8Array
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.

const deleteResp = await sdk.db.tx.Delete({
  creator: sdk.db.address,
  uuid: 'myUuid',
  key: 'myKey',
})

.....

sdk.db.tx.Delete({
  creator: sdk.db.address,
  uuid: 'myUuid',
  key: 'myKey',
})
	.then(resp => {...})
	.catch(err => {...})

Returns: Promise=>MsgDeleteResponse (empty object)

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

DeleteAll(MsgDeleteAllRequest)

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

const deleteAllResp = await sdk.db.tx.DeleteAll({
  creator: sdk.db.address,
  uuid: 'myUuid',
})

.....

sdk.db.tx.DeleteAll({
  creator: sdk.db.address,
  uuid: 'myUuid',
})
	.then(resp => {...})
	.catch(err => {...})

Returns: Promise=>MsgDeleteAllResponse (empty object)

MsgDeleteAllRequest	Description	Type
creator	Signer address	string
uuid	Database identifier	string

MultiUpdate(MsgMultiUpdateRequest)

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

const myLease = {days: 0, seconds: 0, years: 0, hours: 1, minutes: 0}

const multiUpdateResp = await sdk.db.tx.MultiUpdate({
  creator: sdk.db.address,
  uuid: 'myUuid',
  keyValues: [{key: 'existingKey1', value: 'newValue1', lease: myLease}, {key: 'existingKey2', value: 'newValue2', lease: myLease}]
})

.....

sdk.db.tx.MultiUpdate({
  creator: sdk.db.address,
  uuid: 'myUuid',
  keyValues: [{key: 'existingKey1', value: 'newValue1', lease: myLease}, {key: 'existingKey2', value: 'newValue2', lease: myLease}]
})
	.then(resp => {...})
	.catch(err => {...})

Returns: Promise=>MsgMultiUpdateResponse (empty object)

MsgMultiUpdateRequest	Description	Type
creator	Signer address	string
uuid	Database identifier	string
keyValues	KeyValueLease {key: string, value: Uint8Array, lease: Lease}	KeyValueLease []

*Lease {seconds: number, minutes: number, hours: number, days: number, years: number}

Rename(MsgRenameRequest)

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

const renameResp = await sdk.db.tx.Rename({
  creator: sdk.db.address,
  uuid: 'myUuid',
  key: 'existingKey',
  newKey: 'renamingKey'
})

.....

sdk.db.tx.Rename({
  creator: sdk.db.address,
  uuid: 'myUuid',
  key: 'existingKey',
  newKey: 'renamingKey'
})
	.then(resp => {...})
	.catch(err => {...})

Returns: Promise=>MsgRenameResponse (empty object)

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

RenewLease(MsgRenewLeaseRequest)

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

const renewLeaseResp = await sdk.db.tx.RenewLease({
  creator: sdk.db.address,
  uuid: 'myUuid',
  key: 'existingKey',
  lease: {days: 0, seconds: 0, years: 0, hours: 1, minutes: 0}
})

.....

sdk.db.tx.RenewLease({
  creator: sdk.db.address,
  uuid: 'myUuid',
  key: 'existingKey',
  lease: {days: 0, seconds: 0, years: 0, hours: 1, minutes: 0}
})
	.then(resp => {...})
	.catch(err => {...})

Returns: Promise=>MsgRenewLeaseResponse (empty object)

MsgRenewLeaseRequest	Description	Type
creator	Signer address	string
uuid	Database identifier	string
key		string
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.

const renewLeasesAllResp = await sdk.db.tx.RenewLeasesAll({
  creator: sdk.db.address,
  uuid: 'myUuid',
  lease: {days: 0, seconds: 0, years: 0, hours: 1, minutes: 0}
})

.....

sdk.db.tx.RenewLeasesAll({
  creator: sdk.db.address,
  uuid: 'myUuid',
  lease: {days: 0, seconds: 0, years: 0, hours: 1, minutes: 0}
})
	.then(resp => {...})
	.catch(err => {...})

Returns: Promise=>MsgRenewLeasesAllResponse (empty object)

MsgRenewLeasesAllRequest	Description	Type
creator	Signer address	string
uuid	Database identifier	string
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.

const updateResp = await sdk.db.tx.Update({
  creator: sdk.db.address,
  uuid: 'myUuid',
  key: 'existingKey',
  value: new TextEncoder().encode('newValue'),
  metadata: new Uint8Array(),
  lease: {days: 0, seconds: 0, years: 0, hours: 1, minutes: 0}
})

.....

sdk.db.tx.Update({
  creator: sdk.db.address,
  uuid: 'myUuid',
  key: 'existingKey',
  value: new TextEncoder().encode('newValue'),
  metadata: new Uint8Array(),
  lease: {days: 0, seconds: 0, years: 0, hours: 1, minutes: 0}
})
	.then(resp => {...})
	.catch(err => {...})

Returns: Promise=>MsgUpdateResponse (empty object)

MsgUpdateRequest	Description	Type
creator	Signer address	string
uuid	Database identifier	string
key		string
value	New value to update to	Uint8Array
metadata		Uint8Array
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

const upsertResp = await sdk.db.tx.Upsert({
  creator: sdk.db.address,
  uuid: 'myUuid',
  key: 'keyToUpsert',
  value: new TextEncoder().encode('valueToUpsert'),
  metadata: new Uint8Array(),
  lease: {days: 0, seconds: 0, years: 0, hours: 1, minutes: 0}
})

.....

sdk.db.tx.Upsert({
  creator: sdk.db.address,
  uuid: 'myUuid',
  key: 'keyToUpsert',
  value: new TextEncoder().encode('valueToUpsert'),
  metadata: new Uint8Array(),
  lease: {days: 0, seconds: 0, years: 0, hours: 1, minutes: 0}
})
	.then(resp => {...})
	.catch(err => {...})

Returns: Promise=>MsgUpsertResponse (empty object)

MsgUpsertRequest	Description	Type
creator	Signer address	string
uuid	Database identifier	string
key		string
value		Uint8Array
metadata		Uint8Array
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.

const countResp = await sdk.db.q.Count({
   uuid: "myUuid",
})

.....

sdk.db.q.Count({
  uuid: 'myUuid',
})
	.then(resp => {...})
	.catch(err => {...})

Returns: Promise=>QueryCountResponse

QueryCountRequest	Description	Type
uuid	Database identifier	string

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

GetLease(QueryGetLeaseRequest)

Get the remaining lease time of a key-value.

const getLeaseResp = await sdk.db.q.GetLease({
  uuid: 'myUuid',
  key: 'myKey',
})

.....

sdk.db.q.GetLease({
  uuid: 'myUuid',
  key: 'myKey'
})
	.then(resp => {...})
	.catch(err => {...})

Returns: Promise=>QueryGetLeaseResponse

QueryGetLeaseRequest	Description	Type
uuid	Database identifier	string
key		string

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

GetNShortestLeases(QueryGetNShortestLeasesRequest)

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

const getNLeasesResp = await sdk.db.q.GetNShortestLeases({
   uuid: "myUuid",
   num: 10
})

.....

sdk.db.q.GetNShortestLeases({
  uuid: 'myUuid',
  num: 10
})
	.then(resp => {...})
	.catch(err => {...})

Returns: Promise=>QueryGetNShortestLeasesResponse

QueryGetNShortestLeasesRequest	Description	Type
uuid	Database identifier	string
num	Number of keyLeases to return	number

QueryGetNShortestLeasesResponse	Description	Type
keyLeases	KeyLease {key: string, seconds: number}	KeyLease []

Has(QueryHasRequest)

Check if a key exists in the specified uuid.

const hasResp = await sdk.db.q.Has({
   uuid: "myUuid",
   key: "myKey"
})

.....

sdk.db.q.Has({
  uuid: 'myUuid',
  key: "myKey"
})
	.then(resp => {...})
	.catch(err => {...})

Returns: Promise=>QueryHasResponse

QueryHasRequest	Description	Type
uuid	Database identifier	string
key		string

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

Keys(QueryKeysRequest}

Read the complete set of keys in the specified uuid.

const keysResp = await sdk.db.q.Keys({
  uuid: 'myUuid',
  pagination: {
    startKey: 'key-a'
    limit: Long.fromInt(50)
  }
})

.....

sdk.db.q.Keys({
  uuid: 'myUuid',
  pagination: {
    startKey: 'key-a'
    limit: Long.fromInt(50)
  }
})
	.then(resp => {...})
	.catch(err => {...})

Returns: Promise=>QueryKeysResponse

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

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

KeyValues(QueryKeyValuesRequest)

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

const keyValuesResp = await sdk.db.q.KeyValues({
  uuid: 'myUuid',
  pagination: {
    startKey: 'key-a'
    limit: Long.fromInt(50)
  }
})

.....

sdk.db.q.KeyValues({
  uuid: 'myUuid',
  pagination: {
    startKey: 'key-a'
    limit: Long.fromInt(50)
  }
})
	.then(resp => {...})
	.catch(err => {...})

Returns: Promise=>QueryKeyValuesResponse

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

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

MyKeys(QueryMyKeysRequest)

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

const keysResp = await sdk.db.q.Keys({
  uuid: 'myUuid',
  address: sdk.db.address
})

.....

sdk.db.q.Keys({
  uuid: 'myUuid',
  address: sdk.db.address
})
	.then(resp => {...})
	.catch(err => {...})

Returns: Promise=>QueryMyKeysResponse

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

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

Read(QueryReadRequest)

Read a value from the database.

const readResp = await sdk.db.q.Read({
  uuid: 'myUuid',
  key: 'existingKey'
})

.....

sdk.db.q.Read({
  uuid: 'myUuid',
  key: 'existingKey'
})
	.then(resp => {...})
	.catch(err => {...})

Returns: Promise=>QueryReadResponse

QueryReadRequest	Description	Type
uuid	Database identifier	string
key		string

QueryReadResponse	Description	Type
value		Uint8Array

Search(QuerySearchRequest)

Search by key in the specified uuid.

const searchResp = await sdk.db.q.Search({
  uuid: "myUuid",
  searchString: "keyPrefix",
  pagination: {
    startKey: 'keyPrefix-A'
    limit: Long.fromInt(50)
  }
})

.....

sdk.db.q.Search({
  uuid: 'myUuid',
  searchString: "keyPrefix",
  pagination: {
    startKey: 'keyPrefix-A'
    limit: Long.fromInt(50)
  }
})
	.then(resp => {...})
	.catch(err => {...})

Returns: Promise=>QuerySearchResponse

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

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

@bluzelle/sdk-js

Setup

sdk-js Installation

Quick Start

Websockets vs. HTTPS

Usage

sdk-hierarchy

Queries

Transactions

withTransactions(() => {...})

CRUD (db) module methods

Transactions

Create(MsgCreateRequest)

Delete(MsgDeleteRequest)

DeleteAll(MsgDeleteAllRequest)

MultiUpdate(MsgMultiUpdateRequest)

Rename(MsgRenameRequest)

RenewLease(MsgRenewLeaseRequest)

RenewLeasesAll(MsgRenewLeasesAllRequest)

Update(MsgUpdateRequest)

Upsert(MsgUpsertRequest)

Queries

Count(QueryCountRequest)

GetLease(QueryGetLeaseRequest)

GetNShortestLeases(QueryGetNShortestLeasesRequest)

Has(QueryHasRequest)

Keys(QueryKeysRequest}

KeyValues(QueryKeyValuesRequest)

MyKeys(QueryMyKeysRequest)

Read(QueryReadRequest)

Search(QuerySearchRequest)

Readme

Keywords

Package Sidebar

Install

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads