For Developers

Read our product guide below, or speak directly with our project team on Slack
Join Slack

Latest Developer Update

Developer Guide

Your path to using our database services for the world’s dApps

  • Acquire BLZ tokens

    Buy BLZ tokens into your Ethereum wallet. If on a testnet, use the Bluzelle faucet.

    Depending on which Ethereum network you are on:

    Mainnet

    • Purchase a minimum number of BLZ tokens (ie: USD $500 worth) and store them into an Ethereum account owned by you. BLZ can be purchased directly from Bluzelle for ETH/BTC or from major crypto exchanges.

    Rinkeby/Ropsten

    • If you are developing on a testnet (Rinkeby or Ropsten), look at the Bluzelle development API to get access to the BLZ faucet. Use the “getTokens” function to acquire up to 1K BLZ tokens per day, per Ethereum calling account. The BLZ tokens will be sent to the calling account within one block confirmation.
  • Get Address

    Acquire the Ethereum address of the Bluzelle library smart contract (BLSC).

    Acquire the Ethereum address of the Bluzelle Library Smart Contract (BLSC), which will vary depending on if you are on Mainnet, Rinkeby or Ropsten.

  • Fund DSA

    Fund your BLSC account with a suitable amount of BLZ tokens (ie: USD $100 worth).

    Send a suitable amount of BLZ tokens (ie: USD $100 worth) to the BLSC. The BLSC will hold these tokens in trust for you in your own Database Spending Account (DSA), and will only use these tokens when you issue DB calls to the database from the very same calling Ethereum address.

    At any time, you can withdraw unspent BLZ tokens back to you, provided you initiate this request from the same Ethereum address you funded your DSA with.

  • Import File

    Import the BLSC solidity interface file (bluzelle.sol).

    Import the BLSC solidity interface file (bluzelle.sol) with a function call such as:

    import “Bluzelle.sol”;

  • Instatiate Interface

    Instantiate a calling interface to the BLSC in your smart contract.

    Instantiate a calling interface to the BLSC in your smart contract, as follows:

    contract MySmartContract{
    Bluzelle _bluzelle;
    function MySmartContract(address bluzelleLibrarySmartContractAddress) {
    _bluzelle = Bluzelle(bluzelleLibrarySmartContractAddress);}
    }

    This example requires you to instantiate your own smart contract with the hexadecimal Ethereum address of the BLSC. You can of course perform this logic outside of your smart contract constructor, as needed.

  • Optional Callbacks

    Optionally, implement the callback interface from the BLSC to your smart contract.

    Optionally, inherit your smart contract from the Bluzelle callback abstract interface, to enable functional callbacks to your smart contract from any calls made to Bluzelle (all calls to Bluzelle always result in events also being emitted). Look at the contents of Bluzelle.sol at the different callback interfaces for details. You can implement multiple such interfaces (ie: read and update), as needed.

    An example of implementing the read callback interface:

    contract MySmartContract is BluzelleReadCallback {…function ReadCallback(string strKey, string strValue){}

    …}

    Set up the callback as appropriate, to react to the return value from the database call. In this example, you might want to perform some additional smart contract logic once a value you read from the database has been returned to you.

  • Database Calls

    Make database calls (ie: create, read, update, delete) using the BLSC calling interface.

    Make database calls (ie: create, read, update, delete) using the BLSC calling interface instantiated above:


    _bluzelle.read(“someKey”, true)

    The boolean parameter indicates whether or not Bluzelle should attempt to call back your smart contract when the return value comes back. Typically, it is useful for this value to be true for reads, but note the BLZ cost is higher for such callbacks, to factor in the Ethereum gas cost Bluzelle incurs, of calling your smart contract back.

    ALL calls to Bluzelle are asynchronous (ie: the calls to Bluzelle return immediately, as the “work” is done by the database off-chain), and upon completion, an asynchronous event is emitted by Bluzelle that you can listen for. As indicated above, you can optionally ask Bluzelle to also call your smart contract back directly with the return value.

    The appropriate amount of BLZ will be debited from your BLZ account on the BLSC.

    Note: As part of the Ethereum protocol, you will also be charged a very minimal amount of Ethereum gas to make this transaction (which will be added to the total gas cost of your calling smart contract function). The majority of the “cost” of Bluzelle database calls (Create, Read, Update, Delete) will be borne out of the BLZ account you pre-funded earlier, not Ethereum gas costs.

  • Optional Event Listeners

    React to the responses from the database calls in the optional callback interface or via event listeners.

    Optionally, setup event listeners for all calls made to Bluzelle. For example, a call to read from Bluzelle will result in the following event being emitted:

    event ReadEvent(string strKey, string strValue);

    events, whenever possible, is an effective way to greatly reduce your gas costs, particularly with reads (where a return value is inherently needed). For example, if your software architecture enables it, instead of paying extra BLZ to have Bluzelle call your smart contract directly (ie: on-chain) with the results of a read, simply listen for the ReadEvent, capture the “returned” key and value, and then perform your logic accordingly, including possibly passing these values back into your smart contract.