SDK / CLI Documentation

This guide provides instructions on how to interact with Gridlock's network. It is intended for developers looking to build on Gridlock's storage technology.

---

Initialize SDK

Start by initializing the Gridlock SDK to use the built-in functions.

Parameters:

• apiKey (string): Your API key for authentication into the chosen network.

• baseUrl (string): The URL endpoint for the backend orchestration "orch" node(s).

• verbose (boolean): Set to true to see additional debug information

• logger (object): A logging instance for outputting logs (e.g., console, winston).

SDK Example

const API_KEY = 'your_api_key_here'; 
const BASE_URL = 'https://your_base_url_here'; 
const DEBUG_MODE = true; 

const gridlock = new GridlockSdk({
  apiKey: API_KEY,
  baseUrl: BASE_URL,
  verbose: DEBUG_MODE,
  logger: console,
});

export default gridlock;

---

Create User (createUser)

Description: Creates a new empty user account.

Parameters:

• name (string): The user's full name

• email (string): The user's email address, used for authentication.

• password (string): The user's password for authentication.

• saveCredentials (boolean): Option to save the user's credentials locally for easier management. Use saveStoredCredentialsand clearStoredCredentials functions to switch to another saved user.

Return Value:

• user (object): JSON object containing user account details.

• authTokens (object): JSON object containing temporary authentication tokens for session management.

Example Usage:

SDK Example

SDK Command:

gridlock.createUser({ 
  name: 'Bertram Gilfoyle', 
  email: '[e-mail]',
  password: 'password123',
  saveCredentials: false 
});

Example Usage:

import gridlock from 'initGridlock.js'; 

const { user, authTokens } = await gridlock.createUser({
  name: 'Bertram Gilfoyle',
  email: '[e-mail]',
  password: 'password123',
  saveCredentials: false,
});

console.log('User created:', user.name);
console.log('Email:', user.email);

CLI Example

CLI Command:

gridlock create-user \
  -n "Bertram Gilfoyle" \
  -e [e-mail] \
  -p mypassword

Example Output:

$ gridlock create-user \
  -n "Bertram Gilfoyle" \
  -e [e-mail] \
  -p mypassword \
  -s
  
Entered values:
 User name: Bertram Gilfoyle
 Email: [e-mail]
 Password: *******
 Save credentials: true


✔ ➕ Created account for user: Bertram Gilfoyle

Additional Guidance:

The user's node pool will initiate in an empty state. The next step is to add guardians to the user's storage network.

---

Add Guardian (addGuardian)

Description: Adds a self-hosted guardian to the user's node pool.

Parameters:

• email (string): The user's email address, used for authentication.

• password (string): The user's password for authentication.

• guardian (object): Object containing information about the guardian. Details below.

  • name (string): The guardian’s name.

  • type (string): The type of guardian, currently limited to cloud

  • nodeId (string): Unique identifier for the guardian.

  • publicKey (string): The guardian’s public key used for identification.

  • e2ePublicKey (string): The guardian’s public key used for end-to-end encryption.

• isOwnerGuardian (boolean): Indicates if the user is the owner guardian.

Return Values:

• user (object): JSON object containing user details

• guardian (object): JSON object containing guardian details.

Example Usage:

SDK Example

SDK Command:

gridlock.addGuardian({
  email: '[e-mail]',
  password: 'password123',
  guardian: guardianData,
  isOwnerGuardian: false,
});

Example Usage:

import { IGuardian } from 'gridlock-sdk/types';

const guardianData: IGuardian = {
  name: 'EXAMPLE CLOUD GUARDIAN',
  nodeId: 'f90f889a-01ea-415f-81fe-ed624c6b0541',
  publicKey: 'UDFCR7NI5DJEAUSEIWWBIXBNQQLWBBPSSDSF5AOCMNW5LMZQGOVT7RCC',
  e2ePublicKey: 'Zos8ukwJEL7TFvrtinuV9AQNC2if3rwcb55HJLnpIlQ',
  type: 'cloud',
  active: true,
};

const response = await gridlock.addGuardian({
  email: '[e-mail]',
  password: 'password123',
  guardian: guardianData,
  isOwnerGuardian: false,
});

console.log('Guardian added:', response.guardian.name);

CLI Example

CLI Command:

node dist/gridlock.js add-guardian \
  -t cloud \
  -n "My Cloud Guardian" \
  -i "8e198cc0-eace-4b9b-a12c-7a6e6801078q" \
  -ik "UA2IGJVRR2LXXLUJTBDWRXH55IV2N5JNJQLABEH52COWVWXKYCFVEZJD" \
  -ek "DJeBSqPAN6J3tSy34Ora/Bdl4/B/K13pkOkZv4DNUCc="

Example Usage:

$ node dist/gridlock.js add-guardian \
  -t cloud \
  -n "My Cloud Guardian" \
  -i "8e198cc0-eace-4b9b-a12c-7a6e6801078q" \
  -ik "UA2IGJVRR2LXXLUJTBDWRXH55IV2N5JNJQLABEH52COWVWXKYCFVEZJD" \
  -ek "DJeBSqPAN6J3tSy34Ora/Bdl4/B/K13pkOkZv4DNUCc="
  
  
Entered values:
 Email: [e-mail]
 Password: *******
 Node ID: 8e198cc0-eace-4b9b-a12c-7a6e6801078q
 Name: My Cloud Guardian
 Guardian Type: cloud
 Public Key: UA2IGJVRR2LXXLUJTBDWRXH55IV2N5JNJQLABEH52COWVWXKYCFVEZJD
 E2E Public Key: DJeBSqPAN6J3tSy34Ora/Bdl4/B/K13pkOkZv4DNUCc=


✔ Guardian assigned successfully

Additional Guidance:

---

Add Professional Guardian (addProfessionalGuardian)

Description: Adds a Gridlock-hosted guardian to the user's node pool.

Parameters:

• email (string): The user's email address, used for authentication.

• password (string): The user's password for authentication.

• type (string): The type of professional guardian, either gridlock or partner

Return Values:

• user (object): JSON object containing user details

• guardian (object): JSON object containing guardian details.

Example Usage:

SDK Example

SDK Command:

gridlock.addGridlockGuardian({
  email: '[e-mail]',
  password: 'password123',
  type: 'gridlock',
});

Example Usage:

import { IGuardian } from 'gridlock-sdk/types';

const response = await gridlock.addGridlockGuardian({
  email: '[e-mail]',
  password: 'password123',
  type: 'gridlock',
});

console.log('Gridlock Guardian added:', response.guardian.name);

CLI Example

CLI Command:

gridlock add-guardian \
  -e [e-mail] \
  -p password123 \
  -t partner

Example Usage:

$ gridlock add-guardian \
  -e [e-mail] \
  -p password123 \
  -t gridlock
  
✔ Added Gridlock Guardian (Clarence) to user's list of guardians

Additional Guidance:

Professional Guardians cannot be assigned as “Owner Guardian” because they are not meant to serve as the primary controllers of assets.

---

Create Wallet (createWallet)

Description: Generates a distributed private key and address for the given user and blockchain.

Parameters:

• email (string): The user's email address, used for authentication.

• password (string): The user's password for authentication.

• blockchain (string): Blockchain identifier (e.g., 'DOT', 'BTC', 'ETH')

Return Value:

• wallet (object): JSON object with address information and associated guardians

Example Usage:

SDK Example

SDK Command:

gridlock.createWallet({
  email: '[e-mail]',
  password: 'password123',
  blockchain: 'solana',
});

Example Usage:

const wallet = await gridlock.createWallet({
  email: '[e-mail]',
  password: 'password123',
  blockchain: 'solana',
});

console.log('Wallet created with address: ', wallet.address);

CLI Example

CLI Command:

gridlock create-wallet \
  -e [e-mail] \
  -p password123 \
  -b solana

Example Usage:

$ gridlock create-wallet \
  -e [e-mail] \
  -p password123 \
  -b solana

Entered values:
 Email: [e-mail]
 Password: *******
 Blockchain: solana


✔ ➕ Created Solana wallet with address:
2BoERyoxBjfGJqVfs6DaGp57PiwTbZuCDpT1RqJ7DC15

Additional Guidance:

You must have sufficient guardians assigned before creating a wallet.

The private key is generated using Distributed Key Generation (DKG) through communication with all guardians in the node pool. The key will never exist as a whole.

---

Sign Transaction (signTransaction)

Description: Signs a given transaction for the user.

Parameters:

• email (string): The user's email address, used for authentication.

• password (string): The user's password for authentication.

• address (string): The related blockchain address.

• message (string): The transaction message to be signed.

Return Value:

• signature (object): JSON object containing a signature and other associated data.

Example Usage:

SDK Example

SDK Command:

gridlock.signTransaction({
  email: '[e-mail]',
  password: 'password123',
  address: walletAddress,
  message,
});

Example Output:

const walletAddress = '2BoERyoxBjfGJqVfs6DaGp57PiwTbZuCDpT1RqJ7DC15'
const message = 'This is a message to be signed';

const signature = await gridlock.signTransaction({
  email: '[e-mail]',
  password: 'password123',
  address: walletAddress,
  message,
});

console.log('Message signed:', signature);

CLI Example

CLI Command:

gridlock sign \
  -e [e-mail] \
  -p password123 \
  -m "hello" \
  -a 53tX7BNtA2KxNVassdyjhr5mJdswjJXTtj7tCFXWHTPp

Example Usage:

$ gridlock sign \
  -e [e-mail] \
  -p password123 \
  -m "hello" \
  -a 53tX7BNtA2KxNVassdyjhr5mJdswjJXTtj7tCFXWHTPp


Entered values:
 Email: [e-mail]
 Password: *******
 Address: 2BoERyoxBjfGJqVfs6DaGp57PiwTbZuCDpT1RqJ7DC15
 Message: hello


✔ Transaction signed successfully with signature:
b818f05c332468376c7582136d38fc614d00cf2e3a60a9b58027805823ca7d6fc9764babdf618b455ac00bd75a0535b82c78ad14cf8a2e90c78668704d40d10c

Additional Guidance:

The system gathers partial signatures from the user’s guardians within the node pool. Once enough guardians have signed, the system automatically aggregates them to finalize the transaction.

---

Verify Signature (verifySignature)

Description: Confirms that all nodes in the user's node pool can produce a valid signature for a specified address.

Parameters:

• email (string): The user's email address, used for authentication.

• password (string): The user's password for authentication.

• message (string): The transaction message that you want to verify.

• address (string): The address that signed the message

• signature (string): The signature you want to verify.

Return Value:

• verified (string): A JSON object containing verified as true or false.

Example Usage:

SDK Example

SDK Command:

gridlock.verifySignature({
  email: '[e-mail]',
  password: 'password123',
  message,
  address: walletAddress,
  signature: signature.signature,
});

Example Output:

const walletAddress = '2BoERyoxBjfGJqVfs6DaGp57PiwTbZuCDpT1RqJ7DC15'
const message = 'This is a message to be signed';
const signature = 'b818f05c332468376c7582136d38fc614d00cf2e3a60a9b58027805823ca7d6fc9764babdf618b455ac00bd75a0535b82c78ad14cf8a2e90c78668704d40d10c'

const isVerified = await gridlock.verifySignature({
  email: '[e-mail]',
  password: 'password123',
  message,
  address: walletAddress,
  signature: signature.signature,
});

console.log('Signature verified:', isVerified);

CLI Example

CLI Command:

gridlock verify \
  -e [e-mail] \
  -p password123 \
  -a 53tX7BNtA2KxNVassdyjhr5mJdswjJXTtj7tCFXWHTPp \
  -m "hello" \
  -s b818f05c332468376c7582136d38fc614d00cf2e3a60a9b58027805823ca7d6fc9764babdf618b455ac00bd75a0535b82c78ad14cf8a2e90c78668704d40d10c

Example Usage:

$ gridlock verify \
  -e [e-mail] \
  -p password123 \
  -a 53tX7BNtA2KxNVassdyjhr5mJdswjJXTtj7tCFXWHTPp \
  -m "hello" \
  -s b818f05c332468376c7582136d38fc614d00cf2e3a60a9b58027805823ca7d6fc9764babdf618b455ac00bd75a0535b82c78ad14cf8a2e90c78668704d40d10c
  
Entered values:
 Email: [e-mail]
 Password: *******
 Message: hello
 Address: 53tX7BNtA2KxNVassdyjhr5mJdswjJXTtj7tCFXWHTPp
 Signature: b818f05c332468376c7582136d38fc614d00cf2e3a60a9b58027805823ca7d6fc9764babdf618b455ac00bd75a0535b82c78ad14cf8a2e90c78668704d40d10c


✔ Signature verified successfully:
true
      (👍°ヮ°)👍

Additional Guidance:

Note: Social guardians may not always be online to produce a valid signature, but this does not necessarily mean they are missing from the network or unavailable long-term.

---

CLI-specific commands

---

Show Network (showNetwork)

Description: Lists guardians associated with a specific user.

Parameters:

• email (required, string): Email is used as the unique identifier of the user.

Return Value:

• name (string): The name of the node.

• nodeType (string): The type of node, which can be one of the following:

• nodeId (string): The unique identifier for the node.

• status (string): The current status of the node (e.g., active, inactive).

• identityKey (string): The public key associated with the node identity.

• encryptionKey (string): The public key used by the node for end-to-end encryption.

• ownerGuardian (boolean): Whether the node is designated as the Owner Guardian.

Example Usage:

CLI Example

CLI Command:

gridlock show-network -e [e-mail]

Example Output:

$ gridlock show-network -e [e-mail]

🌐 Guardians for Bertram Gilfoyle ([e-mail])
-----------------------------------
       Name: Oliver
       Type: 🌥️ Cloud Guardian
       Node ID: 8e198cc0-eace-4b9b-a12c-7a6e6801078e
       Status: ACTIVE
       ---
       Name: Gridlock Guardian (Clarence)
       Type: 🛡️ Gridlock Guardian
       Node ID: 8b642223-b9e7-4cf3-b660-4b8542b77977
       Status: ACTIVE
       ---
    👑 Name: James
       Type: 🌥️ Cloud Guardian
       Node ID: f90f889a-01ea-415f-81fe-ed624c6b0541
       Status: ACTIVE
-----------------------------------
Total Guardians: 3 | Threshold: 3 of 3 ✅

Additional Guidance:

Cloud Nodes: These are nodes that you run yourself and are generally run on cloud infrastructure like AWS.

Gridlock Nodes: These nodes are run by Gridlock and perform additional functions like advanced network monitoring for extra protection.

Partner Nodes: These nodes belong to partner organizations that help enhance the network's security and distribution without having control over the user’s assets.