SDK / CLI Documentation

This guide provides detailed instructions on how to interact with Gridlock's network using both CLI commands and SDK functions. This is intended for developers looking to build on Gridlock's storage network

Organization Setup (`orgSetup`)

Description: Initializes an organization on the Gridlock network and make other nodes aware of the new organization.

Parameters:

name (string, required): The name of your organization.
accessKey (string, required): An access key to connect to Gridlock's networking stack

Return Value:

orgId (string): The unique identifier of the organization.

Example Usage:

SDK Example

SDK Command:

gridlock.orgSetup({ name: 'MyOrg', accessKey: 'abc123' });

Example Usage:

const orgId = await gridlock.orgSetup({ 
  name: 'MyOrg', 
  accessKey: 'abc123' 
});

console.log(orgId);
// Output: org_12345

CLI Example

Command:

gridlock org-setup --name MyOrg --accessKey abc123

Example Usage:

$ gridlock org-setup --name MyOrg --accessKey abc123
Setting up organization...
Organization 'MyOrg' has been successfully created.
Organization ID: org_12345

Additional Guidance:

Gridlock uses NATS, a robust and scalable messaging system, for secure distributed communication. By leveraging NATS instead of open public access, we enhance user privacy, strengthen security, and simplify troubleshooting the distributed signing processes.

List Nodes (`listNodes`)

Description: Lists the nodes within the organization's node pool available to every user in the organization or all nodes associated with a specific user, including any social or partner guardians that the user has.

Parameters:

userId (optional, string): The unique identifier of the user. If provided, lists nodes specific to the user, including social and partner guardians. If not provided, lists all nodes available to the organization.

Return Value:

An array of objects, each containing:
- nodeId (string): The node's unique identifier.
- name (string): The name of the node.
- status (string): The status of the node (e.g., active, inactive).
- nodeType (string): The type of node, either 'gridlock', 'partner', or 'social', representing Gridlock's internal nodes, partner guardian nodes, or social guardians respectively.

Example Usage:

SDK Example

SDK Command:

gridlock.listNodes({ userId: 'user123' });

Example Output:

const nodes = await gridlock.listNodes({ userId: 'user123' });

console.log(nodes);
// Output:
// [
//   { nodeId: 'node_01', name: 'Node1', status: 'active', nodeType: 'gridlock' },
//   { nodeId: 'node_02', name: 'Node2', status: 'inactive', nodeType: 'partner' },
//   { nodeId: 'node_03', name: 'Node3', status: 'active', nodeType: 'social' }
// ]

CLI Example

CLI Command:

gridlock list-nodes --userId user123

Example Output:

$ gridlock list-nodes --userId user123
{
  "nodes": [
    { 
      "nodeId": "node_01", 
      "name": "Node1", 
      "status": "active", 
      "nodeType": "gridlock" 
    },
    { 
      "nodeId": "node_02", 
      "name": "Node2", 
      "status": "inactive", 
      "nodeType": "partner" 
    },
    { 
      "nodeId": "node_03", 
      "name": "Node3", 
      "status": "active", 
      "nodeType": "social" 
    }
  ]
}

Additional Guidance:

Gridlock Nodes: These are internal nodes operated by Gridlock which perform additional functions like overall network monitoring. All node pools must include Gridlock nodes to ensure that the user always has access to their vault.

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.

Social Nodes (Social Guardians): These nodes represent the user's trusted contacts, acting as guardians for account recovery or added security. Social nodes play a key role in Gridlock's social recovery process.

Run Node (`runNode`)

Description: Starts a new partner guardian node for the organization using a Docker container. This node will be available to all user storage networks created by the organization.

Parameters:

name (string, required): The name of the node.
nodeKey (string, required): A key that restricts access to the node and its interactions.

Return Value:

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

Example Usage:

SDK Example

SDK Command:

gridlock.runNode({ name: 'MyNode', nodeKey: 'nodekey123' });

Example Output:

const nodeId = await gridlock.runNode({ name: 'MyNode', nodeKey: 'nodekey123' });

console.log(nodeId);
// Output: node_12345

CLI Example

CLI Command:

gridlock run-node --name MyNode --nodeKey nodekey123

Example Output:

$ gridlock run-node --name MyNode --nodeKey nodekey123
Starting node 'MyNode'...
Node started successfully. 
Node ID: node_12345

Additional Guidance:

The access key restricts interactions with the node, allowing only authorized requests. In future updates, this key will ensure that your node is not overloaded due to unrestricted access from any user.

Create User (`createUser`)

Description: Creates a new user account and initializes a user-specific node pool. This pool includes global nodes such as Gridlock Guardians, global Partner Guardians, and nodes running in your organization

Parameters:

userName (string, required): The user's display name.
email (string, required): The email address of the user.

Return Value:

userId (string): The unique identifier for the new user.
userSetupLink (string): A unique, one-time-use link for the user to connect to the network and set up their Gridlock app.

Example Usage:

SDK Example

SDK Command:

gridlock.createUser({ userName: 'JohnDoe', email: 'john@example.com' });

Example Output:

const { userId, userSetupLink } = await gridlock.createUser({ userName: 'JohnDoe', email: 'john@example.com' });

console.log(`UserId: ${userId}, SetupLink: ${userSetupLink}`);
// Output:
// UserId: user_45678, SetupLink: https://setup.gridlock.network/user_45678

CLI Example

CLI Command:

gridlock create-user --userName JohnDoe --email john@example.com

Example Output:

$ gridlock create-user --userName JohnDoe --email john@example.com
Creating user 'JohnDoe'...
User created successfully. UserId: user_45678, SetupLink: https://setup.gridlock.network/user_45678

Additional Guidance:

The user's node pool will initiate in a pending state, and will remain pending until the user completes the setup on their mobile device.

Add Guardian (`addGuardian`)

Description: Adds a guardian to a user's node pool.

Parameters:

userId (string, required): The unique identifier of the user.
guardianName (string, required): The guardian's name.
guardianEmail (string, required): The guardian's email address.

Return Value:

guardianId (string): The unique identifier for the guardian.
guardianSetupLink (string): A unique setup link for the guardian to join the network.

Example Usage:

SDK Example

SDK Command:

gridlock.addGuardian({ userId: 'user123', guardianName: 'Jane Doe', guardianEmail: 'jane@example.com' });

Example Output:

const { guardianId, guardianSetupLink } = await gridlock.addGuardian({ userId: 'user123', guardianName: 'Jane Doe', guardianEmail: 'jane@example.com' });

console.log(`GuardianId: ${guardianId}, SetupLink: ${guardianSetupLink}`);
// Output:
// GuardianId: guardian_987, SetupLink: https://setup.gridlock.network/guardian_987

CLI Example

CLI Command:

gridlock add-guardian --userId user123 --guardianName "Jane Doe" --guardianEmail jane@example.com

Example Output:

$ gridlock add-guardian --userId user123 --guardianName "Jane Doe" --guardianEmail jane@example.com
Adding guardian 'Jane Doe'...
Guardian added successfully. GuardianId: guardian_987, SetupLink: https://setup.gridlock.network/guardian_987

Additional Guidance:

Guardian setup will be pending until they complete the process via the provided link.

Generate Address (`generateAddress`)

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

Parameters:

userId (string, required): The user's unique identifier.
blockchain (string, required): Blockchain identifier (e.g., 'DOT', 'BTC', 'ETH')

Return Value:

address (string): The generated blockchain address for the user.

Example Usage:

SDK Example

SDK Command:

gridlock.generateAddress({ userId: 'user123', blockchain: 'DOT' });

Example Output:

const address = await gridlock.generateAddress({ userId: 'user123', blockchain: 'DOT' });

console.log(address);
// Output: 5GxutyoQaTuPgN...

CLI Example

CLI Command:

gridlock generate-address --userId user123 --blockchain DOT

Example Output:

$ gridlock generate-address --userId user123 --blockchain DOT
Generating Ethereum address for user: user123...
Address generated successfully: 5GxutyoQaTuPgN...

Additional Guidance:

The private key is generated using Distributed Key Generation (DKG) through communication with all guardians in the node pool. The key doesn’t actually exist as a whole, and to view the full key, you must eject it from the system.

Validate Signature (`validateSignature`)

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

Parameters:

userId (string, required): The user's unique identifier.
address (string, required): The address for signature validation.

Return Value:

An array of objects, each detailing:
- nodeId (string): The node's unique identifier.
- status (string): The outcome of the signature validation (success, fail, or missing).

Example Usage:

SDK Example

SDK Command:

gridlock.validateSignature({ userId: 'user123', address: '0x123...' });

Example Output:

const validationResults = await gridlock.validateSignature({ userId: 'user123', address: '0x123...' });

console.log(validationResults);
// Output:
// [
//   { nodeId: 'node_01', status: 'success' },
//   { nodeId: 'node_02', status: 'fail' }
// ]

CLI Example

CLI Command:

gridlock validate-signature --userId user123 --address 0x123...

Example Output:

$ gridlock validate-signature --userId user123 --address 0x123...
Validating signature for address: 0x123...
Validation results:
[
  { nodeId: 'node_01', status: 'success' },
  { nodeId: 'node_02', status: 'fail' }
]

Additional Guidance:

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.

Sign Transaction (`signTransaction`)

Description: Signs a given transaction for the user.

Parameters:

userId (string, required): The user's unique identifier.
address (string, required): The related blockchain address.
unsignedTxn (string, required): The serialized unsigned transaction.

Return Value:

signedTxn (string): The signed transaction.

Example Usage:

SDK Example

SDK Command:

gridlock.signTransaction({ userId: 'user123', address: '0x123...', unsignedTxn: 'rawtxn123' });

Example Output:

const signedTxn = await gridlock.signTransaction({ userId: 'user123', address: '0x123...', unsignedTxn: 'rawtxn123' });

console.log(signedTxn);
// Output: signedtxn456

CLI Example

CLI Command:

gridlock sign-transaction --userId user123 --address 0x123... --unsignedTxn rawtxn123

Example Output:

$ gridlock sign-transaction --userId user123 --address 0x123... --unsignedTxn rawtxn123
Signing transaction...
Transaction signed successfully: 
signedtxn456

Additional Guidance:

The system collects partial signatures from the user's guardians in the node pool. Once a sufficient number of guardians have signed, the system automatically combines them to produce a fully signed transaction.

Here’s the corrected version with the proper parameter and more concise wording:

Eject (`eject`)

Description: Not recommended. This action compiles and reveals the private key for a given blockchain address, bypassing the distributed security model.

Parameters:

userId (string, required): The user's unique identifier.
address (string, required): The blockchain address for which the private key will be derived.

Return Value:

privateKey (string): The full private key.

Example Usage:

SDK Example

SDK Command:

gridlock.eject({ userId: 'user123', address: '0x123...' });

Example Output:

const privateKey = await gridlock.eject({ userId: 'user123', address: '0x123...' });

console.log(privateKey);
// Output: 5HueCGU8rMjxEXxiPuD5BDku4MkFqeZydJUsEJwLVdBhSmUqBVV

CLI Example

CLI Command:

gridlock eject --userId user123 --address 0x123...

Example Output:

$ gridlock eject --userId user123 --address 0x123...
Initiating ejection process...
Private key retrieved successfully: 
5HueCGU8rMjxEXxiPuD5BDku4MkFqeZydJUsEJwLVdBhSmUqBVV

Additional Guidance:

Ejecting a private key compromises the security of Gridlock's distributed storage model, which keeps the key fragmented across guardians for protection. Once ejected, the private key exists in one place, exposing it to risks. This should only be done when absolutely necessary, as it defeats the purpose of Gridlock’s security model.

PreviousTransaction FAQs

Last updated 1 month ago

Organization Setup (orgSetup)

List Nodes (listNodes)

Run Node (runNode)

Create User (createUser)

Add Guardian (addGuardian)

Generate Address (generateAddress)

Validate Signature (validateSignature)

Sign Transaction (signTransaction)

Eject (eject)

Organization Setup (`orgSetup`)

List Nodes (`listNodes`)

Run Node (`runNode`)

Create User (`createUser`)

Add Guardian (`addGuardian`)

Generate Address (`generateAddress`)

Validate Signature (`validateSignature`)

Sign Transaction (`signTransaction`)

Eject (`eject`)