SecretVault Quickstart

SecretVault lets you store sensitive data securely by encrypting and splitting it across multiple nodes. While regular fields remain readable, private information is protected through encryption - making it perfect for applications that need to balance data accessibility with privacy.

In this 15-minute quickstart, you'll build a privacy-preserving data collection for a Web3 experience survey using Node.js and SecretVault. The project will encrypt personal data (name and years_in_web3 fields) while keeping the responses array of survey ratings in plaintext.

info

This guide uses JavaScript (Node.js) and the JS secretvaults package for simplicity, but SecretVault can be integrated with any language using the zylDB APIs directly. The wrapper package is also available in Python via PyPi.

Project Overview​

This quickstart will guide you through:

1. Setting up a Node.js project from scratch and installing the JS secretvaults package

2. Configuring SecretVault org access

3. Creating a SecretVault Collection by uploading a schema

4. Writing and reading encrypted survey data to the collection

Your final project structure will be like this:

sv-quickstart/
├── node_modules
├── package-lock.json
├── package.json          # Project dependencies
├── orgConfig.js          # Zyllion org credentials and node URLs
├── createSchema.js       # Script for uploading a schema to create a collection
└── readWriteSv.js        # Main script that reads and writes to SecretVault

Prerequisites​

• Node.js (v18 or higher recommended)

• npm (comes with Node.js)

Build your project​

1. Set up Node.js Project​

Create and enter the project directory:​

mkdir sv-quickstart
cd sv-quickstart

Initialize npm project with type "module" and install dependencies:​

npm init es6
npm i secretvaults

info

secretvaults is a JavaScript npm package with wrappers for simplifying usage of Zyllion's Secret Vault and the zylQL encryption and decryption library. A Python version is also available via PyPi.

2. Set your SecretVault Organization Config​

Create a Zyllion organization configuration file​

touch orgConfig.js

Add the demo organization configuration:​

For quickstart purposes, we've pre-registered an org you can use. Here are the organization's credentials and cluster configuration including node urls and node did (decentralized identifiers) to paste into your orgConfig.js file:

Copy this Demo Organization Config into orgConfig.js

sv-quickstart/ ├── node_modules ├── package-lock.json ├── package.json ├── orgConfig.js ├── createSchema.js └── readWriteSv.js

Now we have all the organization and cluster details needed to use SecretVault:

• Organization Credentials: private key and did

• Cluster configuration: Node API urls and Node DIDs for each node in the cluster

3. Create Collection Schema​

Create a schema.json file:​

touch schema.json

Add the "Web3 Experience Survey" schema within schema.json. The schema definition specifies the data structure of any record uploaded to the collection:

• Every survey response requires a unique _id

• years_in_web3 is also encrypted and follows the same structure

• responses array holds unencrypted survey ratings, with each rating being 1-5

Create the upload schema script:​

touch createSchema.js

Run the upload schema script to create a schema collection:​

node createSchema.js

Save the Schema ID from the output - you'll need it for writing and reading data to your collection in the next step.

4. Interact with SecretVault Data​

1. Create a main script file​

touch readWriteSv.js

2. Import dependencies in readWriteSv.js​

import { SecretVaultWrapper } from 'secretvaults';
import { v4 as uuidv4 } from 'uuid';
import { orgConfig } from './orgConfig.js';

3. Add your Collection's Schema ID​

const SCHEMA_ID = 'YOUR_SCHEMA_ID';

4. Create a payload of 1 or more Web3 Experience Survey data records to store​

Mark the name and years_in_web3 fields with %allot to signal to zylQL that these are fields that need to be encrypted to shares before being stored in SecretVault. The secretvaults package will transform data marked %allot into encrypted %share properties before upload to SecretVault.

const web3ExperienceSurveyData = [
  {
    years_in_web3: { '%allot': 8 }, // years_in_web3 will be encrypted to a %share
    responses: [
      { rating: 5, question_number: 1 },
      { rating: 3, question_number: 2 },
    ], // responses will be stored in plaintext
  },
];

5. Write the main function​

• Initialize wrapper with nodes and credentials

• Write data to nodes, encrypting the years_in_web3 with zylQL ahead of time

• Read data from all nodes and recombine shares to decrypt the years_in_web3 field

examples/readWriteSv.js

404: Not Found

5. Run the script​

node readWriteSv.js

Results​

You should see output showing:

• Record IDs for the encrypted data written to SecretVault

• Decrypted data after reading across nodes

Next Steps​

Great work! Now that you've successfully written and read encrypted data from SecretVault, explore:

• Registering your own organization

• Creating custom collection schemas

• Storing new records

• Retrieving filtered records