Usage

How to use HollowDB?

HollowDB exposes the following classes:

• an SDK class that exposes basic operations, such as get, put, update and remove.

• an Admin class that additionally exposes higher authorized operations, such as changing the state, transferring ownership, and changing the mode of operation.

Both these are instantiated the same way:

• a signer object that is your account, explained in the next section

• a contractTxId to connect to HollowDB SmartWeave contract

• a warp object instantiated from WarpFactory

import {SDK, Admin} from 'hollowdb';
import {WarpFactory} from 'warp-contracts';

const signer = /* more info on this later */
const warp = WarpFactory.forMainnet();
const sdk = new SDK(signer, contractTxId, warp);
const admin = new Admin(signer, contractTxId, warp);

SDK

SDK provides the basic CRUD (create, read, update, delete) functionality; we refer to these actions as put, get, update, remove respectively.

// we will explain these shortly
import {Prover, computeKey} from 'hollowdb-prover';
const prover = new Prover(WASM_PATH, PROVERKEY_PATH, PROTOCOL);

const key = computeKey(yourSecret);

// GET is open to everyone
await sdk.get(key);

// PUT does not require a proof
await sdk.put(key, value);

// UPDATE with a proof
let {proof: updateProof} = await prover.prove(keyPreimage, curValue, newValue);
await sdk.update(key, newValue, updateProof);

// UPDATE without a proof
await sdk.update(key, newValue);

// REMOVE with a proof
let {proof: removalProof} = await prover.prove(keyPreimage, curValue, null);
await sdk.remove(key, removalProof);

// REMOVE without a proof
await sdk.remove(key);

// read state variables
const {cachedValue} = await sdk.readState();

To learn more about hollowdb-prover, see the following sections:

HollowDB Prover

Usage with Proofs

Admin

The admin has all capabilities of the SDK, and in addition to those, it can alter the contract state!

// update the new owner to be the specified address
await admin.updateOwner(address);

// update verification key for a specific circuit
// e.g. update the `auth` circuit's verification key
await admin.updateVerificationKey("auth", verificationKey);

// update proof requirements for a specific circuit
// e.g. disable proof checking for `auth` circuit
await admin.updateProofRequirement("auth", false);

// update whitelisting requirements for a specific list
// e.g. disable whitelist checking for `put` operations
await admin.updateWhitelistRequirement("put", false);

// add addresses to a whitelist
// e.g. add alice & bob to `put` whitelist
await admin.updateWhitelist([aliceAddr, bobAddr], "put", "add");

// remove addresses from a whitelist
// e.g. remove bob from `update` whitelist
await admin.updateWhitelist([bobAddr], "update", "remove");

This design is made with making HollowDB extendable in mind; that is, we allow for many more types of lists and multiple circuits to be used in HollowDB! We will have more updates in the future that allows extending HollowDB this way.

Admin class has two static utility functions:

• Admin.deploy provides an easy way for you to deploy your own contract to Arweave.

• Admin.evolve allows you to evolve an existing contract to a new source code.