Hello World Tutorial (BurstChain®)¶
If you haven’t yet please read the BurstChain® Introduction before going through with this tutorial.
This tutorial will demonstrate how to create dictionaries, IDs, assets (various operations), and smart contracts.
NOTE: the client-side code is demonstrated here in Java and some pseudo-code; but again any programming language that supports http calls can be used. In the API Client Basics section are examples of Python and CURL; those examples can be extended to this tutorial.
Starting¶
First, BurstIQ will create for you:
- a username/password credential for an admin role
- a new client data-space (known as the client name)
Remember that your “client” name identifies a unique data-space within BurstChain® that segments that your company’s data from others.
The below steps are all done using cURL Commands, the main differences between the commands below are the URL, the Authorization, the Request Body, and the Request Type.
For Burstchain® Endpoints the Authorization header is ID <your-private-id> and for the dictionary calls you use Basic Authorization with your username and password.
Dictionary¶
For this tutorial we will define an “Address” dictionary (chain).
{
"collection": "address",
"indexes": [{
"unique": true,
"attributes": ["id"]
}],
"rootnode": {
"attributes": [{
"name": "id",
"required": true
}, {
"name": "addr1"
}, {
"name": "addr2"
}, {
"name": "city"
}, {
"name": "state"
}, {
"name": "zip"
}]
}
}
Create a string version of the above JSON object and call the PUT for the dictionary endpoint.
curl \
-X PUT \
-u '<username>:<password>' \
-H 'content-type: application/json' \
-d '{
"collection": "address",
"indexes": [{
"unique": true,
"attributes": ["id"]
}],
"rootnode": {
"attributes": [{
"name": "id",
"required": true
}, {
"name": "addr1"
}, {
"name": "addr2"
}, {
"name": "city"
}, {
"name": "state"
}, {
"name": "zip"
}]
}
}'
https://{ASSIGNED_SERVER}.burstiq.com/api/metadata/dictionary
IDs¶
In order to do anything with a chain, the user must have a PrivateID (and for some operations the corresponding PublicID). The PublicID can always be retrievable with the PrivateID.
WARNING: Losing the PrivateID will forfeit all access to data. It is important to secure and not lose this ID!
curl -X GET \
https://{ASSIGNED_SERVER}.burstiq.com/api/burstchain/id/private
curl -X GET \
-H 'authorization: ID <your-private-id>' \
https://{ASSIGNED_SERVER}.burstiq.com/api/burstchain/id/public
Asset¶
Create¶
The following is an example of an asset that might be stored in the BurstChain®.
{
"id": "3456",
"addr1": "123 Main St",
"city": "Somewhere",
"state": "XX",
"zip": "12345"
}
The request to store the asset must contain the owner(s) and an optional assetMetadata (this is additional data that might be useful, but not necessarily part of the actual asset).
{
"owners": [alicePublicId],
"asset": {
"id": "3456",
"addr1": "123 Main St",
"city": "Somewhere",
"state": "XX",
"zip": "12345"
},
"asset_metadata": {"extra": "value"}
}
The request uses the request directly above this.
curl -X POST \
-H 'authorization: ID <your-private-id>' \
-H 'content-type: application/json' \
-d '{
"owners": [
"<your-public-id-goes-here-surrounded-by-double-quotes>"
],
"asset": {
"id": "3456",
"addr1": "123 Main St",
"city": "Somewhere",
"state": "XX",
"zip": "12345"
},
"asset_metadata": {
"extra": "value"
}
}' \
https://{ASSIGNED_SERVER}.burstiq.com/api/burstchain/<some-client-name>/address/asset
Status¶
The user can request the status of the asset (to ensure that the network accepted it).
curl -X GET \
-H 'authorization: ID <your-private-id>' \
https://{ASSIGNED_SERVER}.burstiq.com/api/burstchain/<client-name>/<chain-name>/<asset-id>/status
Get Asset¶
via ID¶
It is possible to request the asset directly via the asset_id.
curl -X GET \
-H 'authorization: ID <your-private-id>' \
https://{ASSIGNED_SERVER}.burstiq.com/api/burstchain/<client-name>/<chain-name>/<asset-id>/latest
via Hash¶
Recall that an asset can be updated, therefore every asset also has a unique hash value. Requesting the asset_id allows the owner to access the history of the asset AND the most current version. Requesting the hash allows the owner to get a specific version of the asset.
curl -X GET \
-H 'authorization: ID <your-private-id>' \
https://{ASSIGNED_SERVER}.burstiq.com/api/burstchain/<client-name>/<chain-name>/<asset-hash>
Update¶
Update the asset with a change in state attribute.
{
"id": "3456",
"addr1": "123 Main St",
"city": "Somewhere",
"state": "XX",
"zip": "12345"
}
Then make the following http client call. The response is a JSON object will contain an asset_id.
{
"assetId": <assetId>,
"asset": {
"id": "3456",
"addr1": "123 Main St",
"city": "Somewhere",
"state": "XX",
"zip": "12345"
}
}
The request for updating an asset must contain the asset_id and the actual asset data, it may also contain any extra metadata that the owner wishes to enhance the asset.
curl -X PUT \
-H 'authorization: ID <your-private-id>' \
-H 'content-type: application/json' \
-d '{
"asset_id": <asset_id>
"asset": {
"id": "3456",
"addr1": "123 Main St",
"city": "Somewhere",
"state": "XX",
"zip": "12345"
},
"asset_metadata": {
"extra": "value"
}
}' \
https://{ASSIGNED_SERVER}.burstiq.com/api/burstchain/<some-client-name>/<chain-name>/asset
Transfer¶
Transferring an asset to another user (ID) requires the current owner to know the new owner’s public id.
{
"asset_id": "0fee39f4-e562-4cef-9aa5-31d0856b310f",
"owners": ["9c7b0cc81285586198d220265ba09f2d69bdb880"],
"new_owners": ["1b30cd1efb1078e30cd5a3e7b93ae5d78eb0358d"],
"new_signer_public_id": "1b30cd1efb1078e30cd5a3e7b93ae5d78eb0358d"
}
Then make the following http client call. The response is a JSON object that contains an asset_id.
The request for transferring an asset contains the asset_id, the current owner (for validation), the new owner(s) and one of them as the signer. The current owner must include their private id in the request for ownership verification.
curl -X POST \
-H 'authorization: ID <your-private-id>' \
-H 'content-type: application/json' \
-d '{
"asset_id": "<asset_id>",
"owners": ["<your-public-id>"],
"new_owners": ["<new-owners-public-id>"],
"new_signer_public_id": "<new-owners-public-id>"
}' \
https://{ASSIGNED_SERVER}.burstiq.com/api/burstchain/%3Csome-client-name%3E/%3Cchain-name%3E/transfer
Query¶
There are multiple ways to query BurstChain® for many assets. As a reminder, only assets that the requestor owns or has been consented to see (via Consent Contract) are available through these query methods.
Query via TQL where clause¶
Create a query as a simple where clause
Example:
{
"tqlWhereClause": "WHERE asset.state = 'XX'"
}
Then use the query object to get any assets owned by the requestor matching the given criteria.
curl -X POST \
-H 'authorization: ID <your-private-id>' \
-H 'content-type: application/json' \
-d '{
"tqlWhereClause": "WHERE asset.state = '\''XX'\''"
}' \
https://{ASSIGNED_SERVER}.burstiq.com/api/burstchain/<your-client-name>/<chain-name>/assets/query
Query via TQL query¶
Similar to the above request, the use of TQL with SELECT can allow more granular selection.
{
"queryTql": "SELECT asset.id FROM address WHERE asset.state = 'XX'"
}
curl -X POST \
-H 'authorization: ID <your-private-id>' \
-H 'content-type: application/json' \
-d '{
"queryTql": "SELECT * FROM <chain-name> WHERE asset.state = '\''XX'\''"
}' \
https://{ASSIGNED_SERVER}.burstiq.com/api/burstchain/<your-client-name>/<chain-name>/assets/query
Query via TQLFlow query¶
Similar to the two requests above, the use of TQLFlow allows you to define just a WHERE clause to query assets.
{
"queryTqlFlow": "WHERE asset.state = 'XX'"
}
curl -X POST \
-H 'authorization: ID <your-private-id>' \
-H 'content-type: application/json' \
-d '{
"queryTqlFlow": "WHERE asset.state = '\''XX'\''"
}' \
https://{ASSIGNED_SERVER}.burstiq.com/api/burstchain/<your-client-name>/<chain-name>/assets/query
Smart Contracts¶
SmartContracts are a way of allowing the user to invoke code over the chain to affect assets (create or transfer) with an on-demand request. There is also the ability to run a general contract that can produce other artifacts than changes to the chain. Finally, the Consent Contract has a special fire-control mechanism, its executed on-access as user query/get requests are made.
Consent¶
Consent Contracts allow a data owner to add or revoke data access permissions for users. A consent contract has a special fire-control mechanism such that it is executed on-access, as user query/get requests are made.
A consent contract cannot be manually invoked. It is implicitly invoked on behalf of the owner when requests for their data are made.
To enable your owned assets to be shared, create a consent contract for a given chain. The code for the consent contract is a simple consent language with conditionals that look like queries. A rule that when evaluates to true grants the requestor access to the data. This means an empty code value will grant the specified requestor access to ALL assets in the chain that are owned by the owner. But restrictions can be made to only grant access to assets that contain specific values.
Example:
consents 4bee39ae99bd1cc0a5bf6d5b42aebb5ecd415b89
for my_chain
when asset.count = 15131
until Date('2018-12-24T12:43:22-0000')
only col3, col4, col5
The “consents” and “for” keywords of the contract are REQUIRED. The “when”, “until”, and “only” are optional parts of the contract. Below is an example of a contract with all keywords set. The “when” clause is TQL syntax.
Request:
{
"contract": "consents 4bee39ae99bd1cc0a5bf6d5b42aebb5ecd415b89 for my_chain when asset.count = 15131 until Date('2018-12-24T12:43:22-0000') only col3, col4, col5",
"name": "my consent",
"smart_contract_type": "consent"
}
Now when the requestor (who was granted consent) queries for data, the data that was subject to this Consent Contract will appear in their query results. In this case, only for a period of time and only specific attributes.
Asset Creation¶
TBD
Asset Transfer¶
TBD
Oracle/Service¶
Future, TBD
Endpoint¶
Use the request object to post the smart contract.
String reqStr = <json request object above>;
final Response response = given(reqSpec)
.body(reqStr)
.header(AUTH_HEADER_NAME, "ID " + alicePrivateId)
.when()
.post("/api/burstchain/{client_name}/{chain_name}/smartcontract", "comp-test", "address")
.then()
.statusCode(200)
.extract()
.response();
For deleting multiple assets you can set a query on the delete assets endpoint that deletes any asset that matches the query.
curl -X DELETE \
-H 'authorization: ID <your-private-id>' \
-H 'content-type: application/json' \
-d '{
"tqlWhereClause": "WHERE asset.state = '\''XX'\''"
}' \
https://{ASSIGNED_SERVER}.burstiq.com/api/burstchain/<your-client-name>/<chain-name>/assets/query