DOCSEARCHbyAlgolia
Submit Docs

GridPlus SDK

website·Indexed 30 days ago

https://gridplus.github.io/gridplus-sdk/

The official TypeScript/JavaScript library for GridPlus, providing a unified signing interface for various formats. The SDK includes APIs for signing (signAuthorization, signMessage), wallet management, address handling, and calldata decoding, with a migration guide available for upgrading from v3.x to v4.0.

Tokens
11.3K
Snippets
75
Records
84
Agent score
74%

What's inside GridPlus SDK

  1. Overview of GridPlus SDK and Lattice1 Architecture

    The GridPlus SDK is the official TypeScript/JavaScript library for the Lattice1 hardware wallet. It establishes a secure communication layer where the SDK encrypts requests, the GridPlus Relay routes them, and the Lattice1 device handles user approval and signing. All communication is end-to-end encrypted using a shared secret established during pairing. User approval requests expire after 2 minutes.

  2. Overview of GridPlus SDK signing workflow

    The GridPlus SDK provides a signing interface for transactions and messages across multiple blockchains using Viem-compatible formats. All communication with the Lattice1 device is end-to-end encrypted. The signing process follows these steps: 1. Create (using Viem's TransactionSerializable format), 2. Serialize (SDK converts to RLP), 3. Encrypt (sent via secure channel), 4. Display (Lattice1 decodes and shows details), 5. Approve (physical user confirmation), 6. Return (signed transaction returned for broadcasting).

  3. Migrate from GridPlus SDK v3.x to v4.0

    When migrating to v4.0, perform the following updates to ensure compatibility with the new Viem-based architecture and Zod validation:

    • Dependencies: Update package.json and replace ethers imports with viem.
    • Transaction Types: Change type from numbers to strings (e.g., 2 becomes 'eip1559').
    • Field Names: Rename gasLimit to gas.
    • Data Types: Convert all numeric values for gas and value to bigint (e.g., 21000n).
    • Utilities: Replace parseEther() with the equivalent function from viem.
    • Client Setup: Update initialization to use the new setup() and pair() functions.
    • Testing: Transition from custom setups to Foundry/Anvil.

  4. Request secp256k1 public keys

    Request public keys for the secp256k1 curve (used by BTC, ETH). The returned keys are 65 bytes long, formatted as 04{X}{Y} (prefixed with 04).
    import { Constants } from 'gridplus-sdk';

const req = {
  startPath: [0x80000000 + 44, 0x80000000 + 60, 0x80000000, 0, 0],
  n: 3,
  flag: Constants.GET_ADDR_FLAGS.SECP256K1_PUB,
};

const pubkeys = await fetchAddresses(req);

  5. Install GridPlus SDK

    Install the GridPlus SDK using npm, yarn, or pnpm. Note that v4.0.0 introduces breaking changes, including a migration from ethers.js to viem.
    # Using npm
npm install --save gridplus-sdk

# Using yarn
yarn add gridplus-sdk

# Using pnpm
pnpm add gridplus-sdk

  6. Request Ethereum-type addresses

    Request Ethereum addresses (20-byte hex strings prefixed with 0x) by specifying a BIP32 derivation path. The coin_type must be supported; Ethereum typically uses 60'. Changing the coin_type will change the resulting addresses.
    const reqData = {
  startPath: [
    // Derivation path: [ purpose, coin_type, account, change, address ]
    0x80000000 + 44, // purpose
    0x80000000 + 60, // coin_type (Ethereum)
    0x80000000,      // account
    0,               // change
    0,               // address
  ],
  n: 5, // Number of sequential addresses to return (max 10)
};

const addrs = await fetchAddresses(reqData);

  7. Manage human-readable address tags on Lattice

    Address tags allow you to associate a human-readable name with a blockchain address. When a transaction request referencing a tagged address is sent to the Lattice, the device displays the tag instead of the raw address string. This applies to EIP712 requests and decoded transaction calldata. Tags are managed via a Key-Value (KV) API where both the key (address) and value (tag) must be up to 64 bytes. Note: Emoji-based tags are currently not supported.

  8. Implement Client Setup and Pairing with the v4.0 Functional API

    v4.0 replaces the Client class with a functional API (setup and pair). This removes the need for manual crypto object management and introduces storage callbacks for automatic state persistence.
    import { setup, pair } from 'gridplus-sdk';

const isPaired = await setup({
  name: 'My App',
  deviceId: 'ABC123',
  password: 'my-secure-password',
  getStoredClient: () => localStorage.getItem('lattice-client'),
  setStoredClient: (client) => localStorage.setItem('lattice-client', client),
});

if (!isPaired) {
  const secret = prompt('Enter pairing code');
  await pair(secret);
}

  9. Reference: SDK Test Suite Commands

    List of available test commands and their requirements regarding the FEATURE_TEST_RUNNER=1 firmware flag.
    # No Device/Firmware Flag Required
npm run test-unit   # SDK unit tests
npm run test        # Integration tests (no Lattice)
npm run e2e-eth     # EIP712 and personal_sign
npm run e2e-gen     # General Lattice message routes
npm run e2e-kv      # KV-files/tags
npm run e2e-ne     # Non-exportable seeded SafeCards

# Requires FEATURE_TEST_RUNNER=1
npm run e2e         # All end-to-end tests
npm run e2e-btc    # BTC signatures
npm run e2e-eip7702 # EIP-7702 authorization
npm run e2e-sign    # All signing tests
npm run e2e-sign-bls # BLS signatures
npm run e2e-sign-determinism # Signature determinism
npm run e2e-sign-evm-abi # ABI decoding/fetching
npm run e2e-sign-evm-tx # EVM transaction types
npm run e2e-sign-solana # Solana transactions
npm run e2e-sign-unformatted # ASCII/hex payloads
npm run e2e-wj      # Wallet jobs/path derivations
npm run contracts   # Local Anvil smart contract interactions

  10. Derive addresses using custom BIP44 paths

    The SDK supports any BIP44-compatible derivation path. Use HARDENED_OFFSET to specify hardened indices in the path array.
    import { fetchAddresses, HARDENED_OFFSET } from 'gridplus-sdk';

// Ethereum (m/44'/60'/0'/0/0)
const ethAddresses = await fetchAddresses({
  startPath: [
    HARDENED_OFFSET + 44, // purpose
    HARDENED_OFFSET + 60, // coin_type
    HARDENED_OFFSET + 0,  // account
    0,                    // change
    0,                    // index
  ],
  n: 10,
});

// Bitcoin Segwit (m/84'/0'/0'/0/0)
const btcSegwit = await fetchAddresses({
  startPath: [
    HARDENED_OFFSET + 84, 
    HARDENED_OFFSET + 0, 
    HARDENED_OFFSET + 0, 
    0, 
    0, 
  ],
});

  11. Request Bitcoin addresses using fetchAddresses

    The Lattice exports three types of Bitcoin addresses based on the purpose index of the BIP32 derivation path. Note that coin_type 0' is required for BTC addresses.

    • Legacy (starts with 1): Set purpose = 44'
    • Wrapped SegWit (starts with 3): Set purpose = 49'
    • SegWit v1 (starts with bc1): Set purpose = 84'
    const reqData = {
  // Example for SegWit v1 (purpose 84')
  startPath: [0x80000000 + 84, 0x80000000, 0x80000000, 0, 0],
};

// n defaults to 10 if not specified
const addr0 = await fetchAddresses(reqData);

  12. Sign Solana transactions

    Use the signSolanaTx function to sign transactions created with the @solana/web3.js library. The payload should contain the Transaction object.
    import { signSolanaTx } from 'gridplus-sdk/api/signing';
import { Transaction, SystemProgram } from '@solana/web3.js';

const transfer = SystemProgram.transfer({
  fromPubkey: fromPublicKey,
  toPubkey: toPublicKey,
  lamports: 1234,
});

const transaction = new Transaction({ recentBlockhash }).add(transfer);

const payload = { tx: transaction };
const result = await signSolanaTx(payload);
// Returns: { tx, txHash, sigs }