Skip to main content

SecretVaults SDK TypeScript Docs

This guide shows how to get started building with the Nillion secretvaults-ts SDK to build applications with Nillion Private Storage.

Install Nillion Dependencies​

npm install @nillion/secretvaults @nillion/nuc

Builder Client Usage​

SecretVaults SDK SecretVaultBuilderClient Usage

info

Prerequisites​

Before building with the SecretVaults SDK, you need:

  1. Nillion Wallet: Create a wallet
  2. Testnet NIL: Get NIL tokens from the Nillion faucet
  3. Get a Nillion API Key with a subscription to nilDB

Initialize a Builder Client​

Initialize the client with your Nillion API Key and a valid nilDB subscription. Connect to nilDB nodes of choice. Call refreshRootToken() after initialization to obtain authentication tokens.

nildb/secretvaults-ts/sdk-examples/client-helpers.ts
loading...

Register Builder Profile​

One-time setup to register your builder profile to the nilDB nodes. Checks if profile exists, creates one if needed, and handles duplicate registration errors.

  • did: Decentralized identifier generated from your API key
  • name: Display name that will be set for your builder profile
nildb/secretvaults-ts/sdk-examples/client-helpers.ts
loading...

Create Collection​

Collections organize and validate your data according to the schema rules. Builders can create "standard" or "owned" collection types.

tip

You can use the Collection Explorer Tool to more easily build and validate a JSON schema for your collection.

Create Standard Collection​

nildb/secretvaults-ts/sdk-examples/standard-collections/create-standard-collection.ts
loading...

Create Owned Collection​

nildb/secretvaults-ts/sdk-examples/owned-collections/create-owned-collection.ts
loading...

Read Collections​

Gets the id, collection type, and name of all collections.

nildb/secretvaults-ts/sdk-examples/shared/read-collections.ts
loading...

Create Records​

Creates new records in a standard collection. Records must match the collection's JSON schema. Use %allot to mark fields for encryption.

  • collection: ID of the target collection
  • data: Array of record objects matching the schema
  • %allot: Special field marker that encrypts the value
tip

Use the no-code Collection Explorer Tool to view the collection and schema

The collection page has an "Example Record Payload" button that will show you the data structure for a record in the collection.

nildb/secretvaults-ts/sdk-examples/standard-collections/create-standard-record.ts
loading...

Read Records​

Finds and retrieves records from a collection using filter criteria. Use the collection explorer to view collections and records.

  • collection: ID of the collection to search
  • filter: Query object to match records (e.g., by _id or other fields)
nildb/secretvaults-ts/sdk-examples/shared/read-collection.ts
loading...

Update Records​

Updates existing records in a collection. Can modify both regular and encrypted fields using MongoDB-style update operators.

  • collection: ID of the target collection
  • filter: Query to match records for updating
  • update: Update operations using $set, $unset, etc.
nildb/secretvaults-ts/sdk-examples/standard-collections/update-record.ts
loading...

Delete Records​

Deletes records from a collection based on filter criteria. Use the collection explorer to verify deletions.

  • collection: ID of the target collection
  • filter: Query to match records for deletion
nildb/secretvaults-ts/sdk-examples/standard-collections/delete-record.ts
loading...

Create Query​

Creates a new saved query in the system using MongoDB-style aggregation pipeline syntax. Queries operate on plaintext fields only - they cannot query encrypted fields (those marked as secret). Queries can be used for simple filtering or complex operations like statistical analysis, data aggregation, and transformations. Once saved, queries can be parameterized with variables and reused across different executions.

tip

Queries support the full range of MongoDB aggregation operations on plaintext fields - from simple $match filters to complex statistical calculations using $group, $avg, $min, $max, and more. Encrypted fields cannot be queried. Reference the Query Examples section to see how to structure aggregation pipelines for string and number field queries.

This creates a query for a collection with a plaintext age number field. You could create this query for a Contact Book Collection, which has age as a plaintext, optional number field.

const queryId = randomUUID();
const queryRequest: CreateQueryRequest = {
  _id: queryId,
  collection: collectionId,
  name: 'Calculate Age Statistics',
  variables: {},
  pipeline: [
    {
      $match: {
        age: { $exists: true, $ne: null },
      },
    },
    {
      $group: {
        _id: null,
        averageAge: { $avg: '$age' },
        minAge: { $min: '$age' },
        maxAge: { $max: '$age' },
        totalWithAge: { $sum: 1 },
        standardDeviation: { $stdDevPop: '$age' },
      },
    },
  ],
};

const createResponse = await builderClient.createQuery(queryRequest);

Run Query​

Executes a saved query and retrieves the results. Query execution is asynchronous across distributed nodes, requiring polling to get the final results. You can pass variables to parameterize the query at runtime.

  • _id: ID of the saved query to execute
  • variables: Object containing values for any query variables defined in the saved query
  • Polling: Results must be polled as queries execute asynchronously across nodes
  • Timeout: Example shows polling for up to 30 seconds with exponential backoff
nildb/secretvaults-ts/sdk-examples/queries/run-query.ts
loading...

Create Delegation Token​

Creates a delegation token that allows a user client to perform operations on behalf of a builder client. Delegation tokens enable secure, time-limited access without sharing the builder's root credentials.

  • audience(userDid): Specifies which user DID can use this token
  • expiresAt: Unix timestamp when the token becomes invalid
  • build(): Signs the token with the builder's private key
nildb/secretvaults-ts/sdk-examples/owned-collections/create-delegation-token.ts
loading...

User Client Usage​

SecretVaults SDK SecretVaultUserClient Usage

Generate a New User Keypair​

Creates a new cryptographic keypair for user authentication and generates the corresponding decentralized identifier (DID).

nildb/secretvaults-ts/sdk-examples/nuc-helpers.ts
loading...

Initialize a User Client​

Initialize the user client with their user keypair or get their Keypair from the user's private key.

nildb/secretvaults-ts/sdk-examples/client-helpers.ts
loading...

Create Owned Records​

Creates user-owned records with access control permissions. Unlike standard records, owned records have explicit ownership and can grant specific access rights to other users.

  • owner: User ID that owns the data
  • data: Array of record objects
  • acl: Access control list defining permissions for other users (in this case the granteeDid)
  • delegationToken: Token from the builder allowing the user to perform the operation on the builder's collection
nildb/secretvaults-ts/sdk-examples/owned-collections/create-owned-data.ts
loading...

List Owned Records​

Retrieves a list of all data references owned by the user client, showing which collections contain the user's data.

  • listDataReferences(): Returns all data references for the authenticated user
  • collection: ID of the collection containing the user's data
  • document/record: ID of the specific record owned by the user
  • builderClient: ID of the builder client that created the collection
nildb/secretvaults-ts/sdk-examples/owned-collections/list-owned-records.ts
loading...

Read Owned Record​

Retrieves a specific owned record by its ID from a collection. Only the record owner or users with granted read access can retrieve the data.

  • collection: ID of the collection containing the record
  • document: ID of the specific record to retrieve
  • readData(): Fetches the record data with decrypted fields
nildb/secretvaults-ts/sdk-examples/owned-collections/read-owned-record.ts
loading...

Delete Owned Record​

Deletes a specific owned record from a collection. Only the record owner can delete their data.

  • collection: ID of the collection containing the record
  • document: ID of the specific record to delete
  • deleteData(): Removes the record from the collection permanently
nildb/secretvaults-ts/sdk-examples/owned-collections/delete-owned-record.ts
loading...

Grant Access​

Grants specific permissions to another user for accessing an owned record. The record owner can control read, write, and execute permissions.

  • grantee: DID of the user receiving access permissions
  • read/write/execute: Boolean flags for specific permission types
  • collection: ID of the collection containing the record
  • document: ID of the specific record to grant access to
nildb/secretvaults-ts/sdk-examples/owned-collections/grant-access.ts
loading...

Revoke Access​

Removes previously granted permissions from a user for accessing an owned record. Only the record owner can revoke access permissions.

  • collection: ID of the collection containing the record
  • document: ID of the specific record to revoke access from
  • grantee: DID of the user whose access is being revoked
  • revokeAccess(): Removes all permissions for the specified user
nildb/secretvaults-ts/sdk-examples/owned-collections/revoke-access.ts
loading...

Integration Examples​

Standard Collection Example​

Complete workflow demonstrating standard collection operations: creating a collection, adding multiple records, updating data, deleting records, and viewing the final state.

Full Example Code
nildb/secretvaults-ts/sdk-examples/standard-collections/full-example-standard.ts
loading...

Owned Collection Example​

Complete example demonstrating the full workflow for owned data collections: creating a user, delegation tokens, owned collections, and data with access control.

Full Example Code
nildb/secretvaults-ts/sdk-examples/owned-collections/full-example-owned.ts
loading...

Query Examples​

Complete working examples demonstrating MongoDB-style aggregation queries on plaintext fields. Each example includes collection setup, sample data creation, multiple query types, and result processing. These show the full range of operations possible on unencrypted data in Private Storage.

Querying String Fields​

Demonstrates text-based queries including exact matches, pattern matching with regex, case-insensitive searches, prefix/suffix filtering, and text aggregations. Examples use the plaintext name field from a contact book schema.

Querying String Fields Example Code
nildb/secretvaults-ts/sdk-examples/queries/plaintext-string-query-example.ts
loading...

Querying Number Fields​

Demonstrates numeric queries including exact values, range filtering, mathematical comparisons, statistical calculations (avg, min, max, standard deviation), grouping by numeric ranges, and sorting with pagination. Examples use the plaintext age field from a contact book schema.

Querying Number Fields Example Code
nildb/secretvaults-ts/sdk-examples/queries/plaintext-number-query-example.ts
loading...

Full SDK Reference Docs​

Complete TypeScript documentation for all methods and types is available at: https://nillion.pub/secretvaults-ts/modules.html

SecretVaultBuilderClient​

  • Class for standard data collections with comprehensive CRUD operations and collection management.

  • Key Methods: createCollection, createStandardData, findData, updateData, deleteData, register, readProfile, refreshRootToken, createQuery, runQuery

SecretVaultUserClient​

  • Class for user-owned data collections with data access control and permissions.

  • Key Methods: createData, readData, deleteData, grantAccess, revokeAccess, listDataReferences, readProfile

Available Types​

The SDK includes comprehensive TypeScript types for all requests, responses, and data structures.