Pear Worklet WDK API Reference

Package: @tetherto/pear-wrk-wdk

Top-level export: HRPC

Command Methods

Handler Registration Methods

log

• type? (LogType): Optional numeric log level.
• data? (string | null): Optional log payload.

workletStart

Deprecated startup request retained in the shipped type surface.

• enableDebugLogs? (number)
• seedPhrase? (string | null)
• seedBuffer? (string | null)
• config (string): JSON string of network configurations.

Returns:

• status? (string | null)

initializeWDK

• encryptionKey? (string): Base64-encoded decryption key for the encrypted seed buffer.
• encryptedSeed? (string): Base64-encoded encrypted seed buffer.
• config (string): JSON stringified WdkWorkletConfig.

The handler requires encryptionKey and encryptedSeed to be passed together or omitted together. When a seeded WDK instance already exists, the runtime disposes it and closes its generic modules before re-registering the wallets and optional protocols in config.

In beta.10, HRPC generic modules are constructed from context.moduleManagers and config.modules only when that request includes the encrypted seed pair. A seedless reinitialization closes existing module instances without reconstructing them. Supply both seed fields on every initialization that must construct or reconstruct modules.

resetWdkWallets

• config (string): JSON stringified object containing a networks map.

The runtime validates config.networks, extracts each target blockchain, calls wdk.dispose(targetChains), and re-registers only those wallet managers. This method does not re-register protocols or close generic modules; existing module instances keep running.

generateEntropyAndEncrypt

• wordCount (12 | 24): The mnemonic word count to generate.

Returns:

• encryptionKey (string)
• encryptedSeedBuffer (string)
• encryptedEntropyBuffer (string)

getMnemonicFromEntropy

• encryptedEntropy (string): Base64-encoded encrypted entropy buffer.
• encryptionKey (string): Base64-encoded decryption key.

Returns:

• mnemonic (string)

getSeedAndEntropyFromMnemonic

• mnemonic (string): Source mnemonic to migrate into encrypted buffers.

Returns:

• encryptionKey (string)
• encryptedSeedBuffer (string)
• encryptedEntropyBuffer (string)

dispose

• args (DisposeRequest): Optional blockchains array. Omit it or pass an empty array for a full disposal.

A full disposal closes all generic modules and clears the WDK instance. A non-empty blockchains array disposes only those wallets and leaves generic modules running.

callMethod

• methodName (string): Account method to invoke.
• network (string): Target blockchain key used to resolve the account.
• accountIndex (number): Account index passed to wdk.getAccount(network, accountIndex).
• args? (string): JSON string of the method arguments.
• options? (string): JSON string of CallMethodOptions.

options.protocolType may be swap, swidge, bridge, lending, or fiat. When present, the runtime requires a non-empty options.protocolName and resolves the protocol-specific account wrapper before invoking methodName. Swidge calls resolve the wrapper with account.getSwidgeProtocol(protocolName).

registerWallet

• config (string): JSON string of network config entries.

Returns:

• status (string)
• blockchains (string): JSON stringified array of registered blockchain names.

registerProtocol

• config (string): JSON string of protocol config entries.

Returns:

• status (string)

callModule

Call one method on a configured generic module. This command is available on HRPC only.

• module (string): Module name shared by RpcContext.moduleManagers and WdkWorkletConfig.modules.
• method (string): Non-empty method name on the constructed module instance.
• args? (string): Optional JSON string of arguments. Arrays are spread as positional arguments; a non-array value is passed as one argument.

Returns CallModuleResponse with optional result, a JSON string. The runtime awaits promises, materializes values with .toArray(), and recursively converts Uint8Array values to hex before serialization.

moduleEvent

Send an HRPC module event to the host.

• module (string): Module name.
• event (string): Event name.
• payload? (string | null): Optional JSON string payload.

onLog

Registers the server-side handler used to service log() requests.

onWorkletStart

Registers the server-side handler used to service the deprecated workletStart() request.

onInitializeWDK

Registers the server-side handler used to service initializeWDK() requests on the worklet side.

onResetWdkWallets

Registers the server-side handler used to service resetWdkWallets() requests on the worklet side.

onGenerateEntropyAndEncrypt

Registers the server-side handler used to service encrypted entropy generation requests.

onGetMnemonicFromEntropy

Registers the server-side handler used to service mnemonic recovery requests.

onGetSeedAndEntropyFromMnemonic

Registers the server-side handler used to service mnemonic migration requests.

onDispose

Registers the server-side handler used to service dispose() requests.

onCallMethod

Registers the server-side handler used to service callMethod() requests.

onRegisterWallet

Registers the server-side handler used to service registerWallet() requests.

onRegisterProtocol

Registers the server-side handler used to service registerProtocol() requests.

onCallModule

Registers the worklet-side handler used to service callModule() requests.

onModuleEvent

Registers the host-side handler used to receive moduleEvent() messages.

Worklet export: registerRpcHandlers(rpc, context)

Import this helper from @tetherto/pear-wrk-wdk/worklet. It registers the package's server-side handlers on the provided RPC instance.

• rpc (any): RPC server instance that supports the generated handler registration methods.
• context (RpcContext): Runtime context containing wdk, WDK, walletManagers, protocolManagers, and wdkLoadError. HRPC generic modules can additionally supply moduleManagers and capabilities; the runtime manages moduleRuntime and moduleInstances.

Types

WdkWorkletConfig

interface WdkWorkletConfig {
  networks: {
    [blockchain: string]: {
      blockchain: string
      config: unknown
    }
  }
  protocols?: {
    [protocolName: string]: {
      blockchain: string
      protocolName: string
      config: unknown
    }
  }
  modules?: {
    [moduleName: string]: Record<string, unknown>
  }
}

The modules map contains runtime module configuration. Its names must match the module managers generated by Worklet Bundler or supplied manually in RpcContext.

WdkModuleManager

interface WdkModuleManager {
  events?: string[]
  createModule: (context: {
    seed: any
    config: any
    capabilities: Record<string, any>
    emit: (event: string, payload?: any) => void
  }) => any | Promise<any>
}

The factory must consume seed synchronously rather than retain it. Module instances can optionally implement close(), suspend(), and resume(). The runtime calls close() during full disposal or reinitialization; targeted blockchain disposal and resetWdkWallets() leave generic modules running. Worklet Bundler-generated HRPC entrypoints forward Bare lifecycle events to suspend() and resume(); manual Pear integrations must wire those events themselves. Declared events are forwarded from the instance, and the injected emit() function can emit events directly.

Module request types

interface CallModuleRequest {
  module: string
  method: string
  args?: string
}

interface CallModuleResponse {
  result?: string | null
}

interface ModuleEventRequest {
  module: string
  event: string
  payload?: string | null
}

WdkResetWalletParams

interface WdkResetWalletParams {
  config: string
}

CallMethodOptions

enum ProtocolType {
  SWAP = 'swap',
  SWIDGE = 'swidge',
  BRIDGE = 'bridge',
  LENDING = 'lending',
  FIAT = 'fiat'
}

interface CallMethodOptions {
  transformResult: Function
  defaultValue: any
  protocolType: ProtocolType
  protocolName: string
}

The published declarations include ProtocolType, but the top-level JavaScript entry does not export that enum value at runtime. Pass the corresponding string literal, such as 'swidge', in serialized request options.

The published CallMethodOptions declaration marks every field as required. The request's options string remains optional at runtime, and the handler reads fields only when their behavior is used.

JSON-RPC Transport

Import registerJsonRpcHandlers() from the separate JSON-RPC entrypoint:

const { registerJsonRpcHandlers } = require('@tetherto/pear-wrk-wdk/jsonrpc')

registerJsonRpcHandlers(ipc, context)

The server reads UTF-8 JSON-RPC 2.0 messages framed with a four-byte unsigned big-endian payload length. Every request requires an ID, and an ID cannot be reused while its earlier request is still in flight. Malformed frames are dropped without a response. The package does not export a JSON-RPC client or native-host helper.

Beta.10 supports these JSON-RPC method names:

• workletStart
• generateEntropyAndEncrypt
• getMnemonicFromEntropy
• getSeedAndEntropyFromMnemonic
• initializeWDK
• callMethod
• registerWallet
• registerProtocol
• dispose

JSON-RPC does not support resetWdkWallets, generic-module calls, or module events in this release. Use HRPC for those operations.

The HRPC and JSON-RPC transports share the callMethod handler, so both support the swidge protocol type in beta.10.

Mnemonic strings, encryption-key strings, and encrypted payload strings cannot be zeroed in JavaScript. Discard references promptly and never log them. The runtime validates imported mnemonics for 12 or 24 English BIP-39 words and clears temporary byte buffers where possible.

Need Help?