# 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).

<details>

<summary>SDK Example</summary>

```typescript

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;
```

</details>

***

## **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.&#x20;
* `saveCredentials` (*boolean*): Option to save the user's credentials locally for easier management. Use `saveStoredCredntials` and `clearStoredCredentials` functions to switch to another saved user.&#x20;

**Return Values**:

* `user` (*object*): JSON object containing user account details.
* `authTokens` (*object*): JSON object containing temporary authentication tokens for session management.

**Example Usage**:

<details>

<summary>SDK Example</summary>

**SDK Command:**

```typescript
gridlock.createUser({ 
  name: 'Bertram Gilfoyle', 
  email: 'john@example.com',
  password: 'password123',
  saveCredentials: false 
});
```

**Example Usage:**

```typescript
import gridlock from 'initGridlock.js'; 

const { user, authTokens } = await gridlock.createUser({
  name: 'Bertram Gilfoyle',
  email: 'gilfoyle@piedpiper.com',
  password: 'password123',
  saveCredentials: false,
});

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

</details>

<details>

<summary>CLI Example</summary>

**CLI Command:**

```bash
gridlock create-user \
  -n "Bertram Gilfoyle" \
  -e gilfoyle@piedpiper.com \
  -p mypassword
```

**Example Usage:**

```bash
$ gridlock create-user \
  -n "Bertram Gilfoyle" \
  -e gilfoyle@piedpiper.com \
  -p mypassword \
  -s
  
Entered values:
 User name: Bertram Gilfoyle
 Email: gilfoyle@piedpiper.com
 Password: *******
 Save credentials: true


✔ ➕ Created account for user: Bertram Gilfoyle
```

</details>

**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.&#x20;

***

## **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**:

<details>

<summary>SDK Example</summary>

**SDK Command:**

```typescript
gridlock.addGuardian({
  email: 'gilfoyle@piedpiper.com',
  password: 'password123',
  guardian: guardianData,
  isOwnerGuardian: false,
});
```

**Example Usage:**

```typescript
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: 'gilfoyle@piedpiper.com',
  password: 'password123',
  guardian: guardianData,
  isOwnerGuardian: false,
});

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

</details>

<br>

***

## **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**:

<details>

<summary>SDK Example</summary>

**SDK Command:**

```typescript
gridlock.addGridlockGuardian({
  email: 'gilfoyle@piedpiper.com',
  password: 'password123',
  type: 'gridlock',
});
```

**Example Usage:**

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

const response = await gridlock.addGridlockGuardian({
  email: 'gilfoyle@piedpiper.com',
  password: 'password123',
  type: 'gridlock',
});

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

</details>

<details>

<summary>CLI Example</summary>

**CLI Command:**

```bash
gridlock add-guardian \
  -e gilfoyle@piedpiper.com \
  -p password123 \
  -t partner
```

**Example Usage:**

```bash
$ gridlock add-guardian \
  -e gilfoyle@piedpiper.com \
  -p password123 \
  -t gridlock
  
✔ Added Gridlock Guardian (Clarence) to user's list of guardians

```

</details>

**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**:

<details>

<summary>SDK Example</summary>

**SDK Command:**

```typescript
gridlock.createWallet({
  email: 'gilfoyle@piedpiper.com',
  password: 'password123',
  blockchain: 'solana',
});
```

**Example Usage:**

```typescript
const wallet = await gridlock.createWallet({
  email: 'gilfoyle@piedpiper.com',
  password: 'password123',
  blockchain: 'solana',
});

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

</details>

<details>

<summary>CLI Example</summary>

**CLI Command:**

```bash
gridlock create-wallet \
  -e gilfoyle@piedpiper.com \
  -p password123 \
  -b solana
```

**Example Usage:**

```bash
$ gridlock create-wallet \
  -e gilfoyle@piedpiper.com \
  -p password123 \
  -b solana

Entered values:
 Email: gilfoyle@piedpiper.com
 Password: *******
 Blockchain: solana


✔ ➕ Created Solana wallet with address:
2BoERyoxBjfGJqVfs6DaGp57PiwTbZuCDpT1RqJ7DC15
```

</details>

**Additional Guidance**:

You must have sufficient guardians assigned before creating a wallet.&#x20;

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.&#x20;

**Example Usage**:

<details>

<summary>SDK Example</summary>

**SDK Command:**

```typescript
gridlock.signTransaction({
  email: 'gilfoyle@piedpiper.com',
  password: 'password123',
  address: walletAddress,
  message,
});
```

**Example Usage:**

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

const signature = await gridlock.signTransaction({
  email: 'gilfoyle@piedpiper.com',
  password: 'password123',
  address: walletAddress,
  message,
});

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

</details>

<details>

<summary>CLI Example</summary>

**CLI Command:**

```bash
gridlock sign \
  -e gilfoyle@piedpiper.com \
  -p password123 \
  -m "hello" \
  -a 53tX7BNtA2KxNVassdyjhr5mJdswjJXTtj7tCFXWHTPp
```

**Example Usage:**

```bash
$ gridlock sign \
  -e gilfoyle@piedpiper.com \
  -p password123 \
  -m "hello" \
  -a 53tX7BNtA2KxNVassdyjhr5mJdswjJXTtj7tCFXWHTPp


Entered values:
 Email: gilfoyle@piedpiper.com
 Password: *******
 Address: 2BoERyoxBjfGJqVfs6DaGp57PiwTbZuCDpT1RqJ7DC15
 Message: hello


✔ Transaction signed successfully with signature:
b818f05c332468376c7582136d38fc614d00cf2e3a60a9b58027805823ca7d6fc9764babdf618b455ac00bd75a0535b82c78ad14cf8a2e90c78668704d40d10c
```

</details>

**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.&#x20;

***

## **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.&#x20;
* `address` (*string*): The address that signed the message
* `signature` (*string*): The signature you want to verify.&#x20;

**Return Value**:

* `verified` (*object*): A JSON object containing verified as true or false.&#x20;

**Example Usage**:

<details>

<summary>SDK Example</summary>

**SDK Command:**

```typescript
gridlock.verifySignature({
  email: 'gilfoyle@piedpiper.com',
  password: 'password123',
  message,
  address: walletAddress,
  signature: signature.signature,
});
```

**Example Usage:**

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

const isVerified = await gridlock.verifySignature({
  email: 'gilfoyle@piedpiper.com',
  password: 'password123',
  message,
  address: walletAddress,
  signature: signature.signature,
});

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

</details>

<details>

<summary>CLI Example</summary>

**CLI Command:**

```bash
gridlock verify \
  -e gilfoyle@piedpiper.com \
  -p password123 \
  -a 53tX7BNtA2KxNVassdyjhr5mJdswjJXTtj7tCFXWHTPp \
  -m "hello" \
  -s b818f05c332468376c7582136d38fc614d00cf2e3a60a9b58027805823ca7d6fc9764babdf618b455ac00bd75a0535b82c78ad14cf8a2e90c78668704d40d10c
```

**Example Usage:**

```bash
$ gridlock verify \
  -e gilfoyle@piedpiper.com \
  -p password123 \
  -a 53tX7BNtA2KxNVassdyjhr5mJdswjJXTtj7tCFXWHTPp \
  -m "hello" \
  -s b818f05c332468376c7582136d38fc614d00cf2e3a60a9b58027805823ca7d6fc9764babdf618b455ac00bd75a0535b82c78ad14cf8a2e90c78668704d40d10c
  
Entered values:
 Email: gilfoyle@piedpiper.com
 Password: *******
 Message: hello
 Address: 53tX7BNtA2KxNVassdyjhr5mJdswjJXTtj7tCFXWHTPp
 Signature: b818f05c332468376c7582136d38fc614d00cf2e3a60a9b58027805823ca7d6fc9764babdf618b455ac00bd75a0535b82c78ad14cf8a2e90c78668704d40d10c


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

</details>

***

## **Start Recovery (`startRecovery`)**

**Description**: Initiates the account recovery process with a user's email.&#x20;

**Parameters**:

* `email` (*string*): The user's email address
* `password` (*string*): New (or previous) password used to encrypt locally stored credentials.&#x20;

**Return Value**:

* `guardians` (*object*): A JSON object containing the list of guardians associated with that user.&#x20;

**Example Usage**:

<details>

<summary>SDK Example</summary>

**SDK Command:**

```typescript
gridlock.startRecovery({
  email: 'gilfoyle@piedpiper.com',
  password: 'my_new_password123',
});
```

**Example Usage:**

```typescript

const guardians = await gridlock.startRecovery({
  email: 'gilfoyle@piedpiper.com',
  password: 'my_new_password123',
});

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

</details>

<details>

<summary>CLI Example</summary>

**CLI Command:**

```bash
gridlock start-recovery \
  -e gilfoyle@piedpiper.com \
  -p my_new_password123
```

**Example Usage:**

<pre class="language-bash"><code class="lang-bash">$ gridlock start-recovery \
  -e gilfoyle@piedpiper.com \
  -p my_new_password123
  
<strong>Entered values:
</strong> Email: gilfoyle@piedpiper.com
 Password: *******


✔ Recovery initiated
</code></pre>

</details>

**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.&#x20;

**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.&#x20;

**Example Usage**:

<details>

<summary>SDK Example</summary>

**SDK Command:**

```typescript
gridlock.confirmRecovery({
  email: 'gilfoyle@piedpiper.com',
  password: 'my_new_password123',
  recoveryBundle: 'M734hwNm9c3OcygBVjkkmDc.....4lo13fNuRJ/9ssTQFegGRcLDA='
});
```

**Example Usage:**

<pre class="language-typescript"><code class="lang-typescript">
const { user, wallets } = await gridlock.confirmRecovery({
  email: 'gilfoyle@piedpiper.com',
  password: 'my_new_password123',
   recoveryBundle: 'M734hwNm9c3OcygBVjkkmDc.....4lo13fNuRJ/9ssTQFegGRcLDA='
});

<strong>console.log('User:', JSON.stringify(user, null, 2));
</strong>console.log('Wallets:', JSON.stringify(wallets, null, 2));
</code></pre>

</details>

<details>

<summary>CLI Example</summary>

**CLI Command:**

```bash
gridlock confirm-recovery \
  -e gilfoyle@piedpiper.com \
  -p my_new_password123 \
  -r recoveryBundle: 'M734hwNm9c3OcygBVjkkmDc.....4lo13fNuRJ/9ssTQFegGRcLDA='
```

**Example Usage:**

```bash
$ gridlock confirm-recovery \
  -e gilfoyle@piedpiper.com \
  -p my_new_password123 \
  -r recoveryBundle: 'M734hwNm9c3OcygBVjkkmDc.....4lo13fNuRJ/9ssTQFegGRcLDA='
  
Entered values:
 Email: gilfoyle@piedpiper.com
 Password: *******
 Recovery Bundle: M734hwNm9c3OcygBVjkkmDc.....4lo13fNuRJ/9ssTQFegGRcLDA=


✔ Recovery confirmed successfully.
```

</details>

**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.&#x20;

***

## **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.&#x20;

**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.&#x20;

**Example Usage**:

<details>

<summary>SDK Example</summary>

**SDK Command:**

```typescript
gridlock.transferOwner({
  email: 'gilfoyle@piedpiper.com',
  password: 'my_new_password123',
});
```

**Example Usage:**

```typescript
const success = await gridlock.transferOwner({
  email: 'gilfoyle@piedpiper.com',
  password: 'my_new_password123',
});

console.log(success);
```

</details>

<details>

<summary>CLI Example</summary>

**CLI Command:**

```bash
gridlock transfer-owner \
  -e gilfoyle@piedpiper.com \
  -p my_new_password123
```

```bash
$ gridlock transfer-owner \
  -e gilfoyle@piedpiper.com \
  -p my_new_password123
  
EEntered values:
 Email: gilfoyle@piedpiper.com
 Password: *******


✔ Ownership successfully transferred to this device
```

</details>

**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.&#x20;

***

## 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.&#x20;

**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.&#x20;
* `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**:

<details>

<summary>CLI Example</summary>

**CLI Command:**

```bash
gridlock show-network -e gilfoyle@piedpiper.com
```

**Example Output:**

```bash
$ gridlock show-network -e gilfoyle@piedpiper.com

🌐 Guardians for Bertram Gilfoyle (gilfoyle@piedpiper.com)
-----------------------------------
       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 ✅
```

</details>

**Additional Guidance**:

**Cloud Nodes:** These are nodes that you run yourself and are generally run on cloud infrastructure like AWS.&#x20;

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

**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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gridlock.network/developer-docs/sdk-cli-documentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.