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 used to encrypt access key stored locally.

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

Return Values:

• 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 Usage:

$ 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 local decryption of access key.

• 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);

---

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 local decryption of access key.

• 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 local decryption of access key.

• 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 local decryption of access key.

• 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 Usage:

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. It's possible for this process to fail in guardians are offline. This itself is a form of security where you can choose to have guardians regularly offline so that transactions are not possible.

---

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 local decryption of access key.

• 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 (object): 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 Usage:

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
      (👍°ヮ°)👍

---

Start Recovery (startRecovery)

Description: Initiates the account recovery process with a user's email.

Parameters:

• email (string): The user's email address

• password (string): New (or previous) password used to encrypt locally stored credentials.

Return Value:

• guardians (object): A JSON object containing the list of guardians associated with that user.

Example Usage:

SDK Example

SDK Command:

gridlock.startRecovery({
  email: '[e-mail]',
  password: 'my_new_password123',
});

Example Usage:

const guardians = await gridlock.startRecovery({
  email: '[e-mail]',
  password: 'my_new_password123',
});

console.log('Guardians:', JSON.stringify(guardians, null, 2));

CLI Example

CLI Command:

gridlock start-recovery \
  -e [e-mail] \
  -p my_new_password123

Example Usage:

$ gridlock start-recovery \
  -e [e-mail] \
  -p my_new_password123
  
Entered values:
 Email: [e-mail]
 Password: *******


✔ Recovery initiated

Additional Guidance:

If the user is found, an email will also be sent to the address they registered with their guardians when they first created the account.

Recovery in this distributed system functions similarly to the “forgot password” process in a traditional system. If the user exists, this call returns a list of their associated guardians. This list is used for future end-to-end encrypted communication during the recovery process.

---

Confirm Recovery (confirmRecovery)

Description: Confirms ownership of email address by sharing the recovery code with the guardian.

Parameters:

• email (string): The user's email address

• password (string): The user's password for local decryption of access key.

• recoveryBundle (string): Information sent by the guardian to the user's email.

Return Value:

• user (object): A JSON object containing the user's information.

• wallets (object): A JSON object containing all wallets associated with that user.

Example Usage:

SDK Example

SDK Command:

gridlock.confirmRecovery({
  email: '[e-mail]',
  password: 'my_new_password123',
  recoveryBundle: 'M734hwNm9c3OcygBVjkkmDc.....4lo13fNuRJ/9ssTQFegGRcLDA='
});

Example Usage:

const { user, wallets } = await gridlock.confirmRecovery({
  email: '[e-mail]',
  password: 'my_new_password123',
   recoveryBundle: 'M734hwNm9c3OcygBVjkkmDc.....4lo13fNuRJ/9ssTQFegGRcLDA='
});

console.log('User:', JSON.stringify(user, null, 2));
console.log('Wallets:', JSON.stringify(wallets, null, 2));

CLI Example

CLI Command:

gridlock confirm-recovery \
  -e [e-mail] \
  -p my_new_password123 \
  -r recoveryBundle: 'M734hwNm9c3OcygBVjkkmDc.....4lo13fNuRJ/9ssTQFegGRcLDA='

Example Usage:

$ gridlock confirm-recovery \
  -e [e-mail] \
  -p my_new_password123 \
  -r recoveryBundle: 'M734hwNm9c3OcygBVjkkmDc.....4lo13fNuRJ/9ssTQFegGRcLDA='
  
Entered values:
 Email: [e-mail]
 Password: *******
 Recovery Bundle: M734hwNm9c3OcygBVjkkmDc.....4lo13fNuRJ/9ssTQFegGRcLDA=


✔ Recovery confirmed successfully.

Additional Guidance:

The recovery bundle contains information about the specific guardian that sent the code as well as a unique challenge that lets the user prove they have access to the correct email.

---

Transfer Owner (transferOwner)

Description: Transfers primary ownership of the account to a new client device, assuming sufficient guardians have been updated via the Confirm Recovery action.

Parameters:

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

• password (string): The user's password for local decryption of access key.

Return Value:

• success (bool): Booleen value showing success or failure of transfer request.

Example Usage:

SDK Example

SDK Command:

gridlock.transferOwner({
  email: '[e-mail]',
  password: 'my_new_password123',
});

Example Usage:

const success = await gridlock.transferOwner({
  email: '[e-mail]',
  password: 'my_new_password123',
});

console.log(success);

CLI Example

CLI Command:

gridlock transfer-owner \
  -e [e-mail] \
  -p my_new_password123

$ gridlock transfer-owner \
  -e [e-mail] \
  -p my_new_password123
  
EEntered values:
 Email: [e-mail]
 Password: *******


✔ Ownership successfully transferred to this device

Additional Guidance:

This function only succeeds if enough guardians have already confirmed the new device. The orch node checks the current status of each guardian. If the required number have approved, it updates the account to make the new client device the one that can log into the network.

---

CLI-specific commands

---

Show Network (showNetwork)

Description: Shows guardians associated with a specific user.

Parameters:

• email (required, string): The 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.