Add convenience method for loading wallet from directory (Node.js)

[jvsteiner]

Problem

Loading a wallet from a directory requires ~25 lines of boilerplate that every Node.js consumer reimplements:

import { existsSync, readFileSync } from 'node:fs';
import { join } from 'node:path';
import { Sphere } from '@unicitylabs/sphere-sdk';
import { createNodeProviders } from '@unicitylabs/sphere-sdk/impl/nodejs';

const mnemonicPath = join(walletDir, 'mnemonic.txt');
const mnemonic = readFileSync(mnemonicPath, 'utf-8').trim();
const trustBasePath = join(walletDir, 'trustbase.json');

const providers = createNodeProviders({
  network: 'testnet',
  dataDir: walletDir,
  tokensDir: join(walletDir, 'tokens'),
  oracle: { trustBasePath, apiKey: '...' },
  transport: { debug: true },
});

const { sphere } = await Sphere.init({ ...providers, mnemonic });

Every consumer must know:

• The mnemonic lives at <dir>/mnemonic.txt
• The trustbase lives at <dir>/trustbase.json
• Tokens go in <dir>/tokens/
• The correct way to assemble createNodeProviders config
• How to pass it all into Sphere.init

We built two marketplace skills that both have identical loadWallet() functions wrapping this boilerplate.

Context

The createNodeProviders helper already crosses the "node-specific convenience" line — it's exported from @unicitylabs/sphere-sdk/impl/nodejs specifically for Node.js consumers. A higher-level loadFromDir() would be a natural extension of that pattern.

The OpenClaw Unicity plugin creates wallets at ~/.openclaw/unicity/ with this exact directory layout. Any skill or application that reads from that shared wallet directory writes the same loading code.

Proposed Solution

Add a convenience function to the Node.js entrypoint:

import { loadWallet } from '@unicitylabs/sphere-sdk/impl/nodejs';

const sphere = await loadWallet('~/.openclaw/unicity/', {
  network: 'testnet',      // optional, default: 'testnet'
  apiKey: '...',            // optional, has default
  transportDebug: false,    // optional
});

This would:

• Read mnemonic.txt from the directory
• Locate trustbase.json automatically
• Configure providers with sensible defaults
• Return an initialized Sphere instance
• Throw a clear error if the wallet directory doesn't exist or has no mnemonic

Alternatives

• Document the pattern — add a "loading from directory" example to the README. Doesn't eliminate duplication but at least gives a canonical reference.
• Separate package — e.g. @unicitylabs/sphere-node-utils. Avoids adding node-specific code to the SDK, but createNodeProviders already sets that precedent.

🤖 Generated with Claude Code

[KruGoL]

Changes

• ``walletFileNameoption increateNodeProviders()` — no longer locked to `wallet.json`. Supports custom filenames including `.txt`.
• .txt file support — FileStorageProvider reads a .txt file as a raw mnemonic (plaintext or encrypted), no JSON wrapper needed.
• password option in Sphere.init()` — optional AES encryption for the mnemonic. Plaintext by default.
• Plaintext mnemonic in wallet.json` — external apps can write a mnemonic directly without SDK-specific encryption.
• Backwards compatible — wallets encrypted with the old default key still load without a password.

Examples

// Point SDK at a directory with a mnemonic.txt file
const providers = createNodeProviders({
  dataDir: walletDir,
  walletFileName: 'mnemonic.txt',
  tokensDir: join(walletDir, 'tokens'),
});
const { sphere } = await Sphere.init({ ...providers });

// With password encryption
const { sphere } = await Sphere.init({
  ...providers,
  password: 'my-secret',
});

Why not loadWallet(dir)?

A one-liner helper was considered, but the remaining boilerplate is now just a configuration object — adding a dedicated function would increase API surface without meaningful simplification.