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.13, generic modules on either transport 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).

When RpcContext.allowedMethods defines the target surface, methodName must appear in its methods array. Account restrictions are keyed by network; protocol restrictions are nested by network, protocol type, and protocol name. Omitted surfaces remain unrestricted, while methods: [] denies every call on that exact surface. Denied calls fail before dispatch with the runtime code METHOD_NOT_ALLOWED.

A missing wallet or protocol method fails with BAD_REQUEST. Beta.13 removes the options.defaultValue fallback from both runtime dispatch and CallMethodOptions; callers must handle unsupported methods themselves.

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. Both HRPC and JSON-RPC support this operation in beta.13.

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

HRPC returns CallModuleResponse with optional result, a JSON string. JSON-RPC decodes that string and returns the value at response.result.result. The runtime awaits promises, materializes values with .toArray(), and recursively converts Uint8Array values to hex before serialization. Return a JSON-serializable value, or null for no result; an undefined result cannot be decoded by the JSON-RPC transport.

When RpcContext.allowedModuleMethods defines the target module, method must appear in that module's methods array. Omitted modules remain unrestricted, while methods: [] denies every method on that module. A denied call fails with METHOD_NOT_ALLOWED before instance lookup or dispatch.

moduleEvent

Send an HRPC module event to the host. JSON-RPC forwards the same event as a moduleEvent notification with decoded params.payload; it has no request id.

• 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. Generic modules on either transport can additionally supply moduleManagers and capabilities; the runtime manages moduleRuntime and moduleInstances. Optional allowedMethods restricts wallet and protocol dispatch on HRPC and JSON-RPC, while allowedModuleMethods restricts generic-module dispatch on both transports.

Types

RpcContext Method Restrictions

interface ProtocolAllowedMethods {
  methods?: string[]
}

interface ProtocolNameAllowedMethods {
  [protocolName: string]: ProtocolAllowedMethods
}

interface ProtocolTypeAllowedMethods {
  [protocolType: string]: ProtocolNameAllowedMethods
}

interface NetworkAllowedMethods extends ProtocolAllowedMethods {
  protocols?: ProtocolTypeAllowedMethods
}

interface RpcContext {
  // Other runtime fields...
  allowedMethods?: Record<string, NetworkAllowedMethods>
  allowedModuleMethods?: Record<string, ProtocolAllowedMethods>
}

The four allowlist helper interfaces are exported types in beta.13. Every omitted level remains unrestricted. Use an explicit empty methods array to deny all dynamic calls on one exact surface.

The runtime exposes METHOD_NOT_ALLOWED for denied calls, but the beta.13 published error-code declaration does not include that member. Treat the literal runtime code as authoritative for this release.

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. Manual Pear integrations must forward Bare lifecycle events to context.moduleRuntime.suspendAll() and resumeAll(); registering either transport alone does not install those listeners. 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
  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 remaining field as required. The request's options string remains optional at runtime, and the handler reads fields only when their behavior is used. transformResult is a function-valued internal handler option; it cannot be sent through JSON serialization. Do not place a function in serialized request options.

Diagnostic export: registerHandleLeakCheck(options?)

Import this helper from @tetherto/pear-wrk-wdk/diagnostics/handle-leak-check:

interface HandleLeakCheckOptions {
  tickIntervalMs?: number
}

function registerHandleLeakCheck(options?: HandleLeakCheckOptions): void

tickIntervalMs is the sampling interval in milliseconds, defaulting to 1000. The helper logs immediately on Bare suspend, repeats with an unreferenced timer, and stops on idle or resume. Handle records include type, native address, isActive, isClosing, and hasRef; it reports rather than closes handles.

Register once per worklet. The helper performs no interval validation and returns without registering listeners when bare-walk-handles or Bare lifecycle events are unavailable. Logs use console.warn independently of LOG_LEVEL. This helper is opt-in; transport registration does not enable it.

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.13 supports these JSON-RPC method names:

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

JSON-RPC does not support resetWdkWallets in this release. Use HRPC for selective wallet resets. Generic modules require context.moduleManagers and matching runtime config.modules; initializeWDK constructs them only when the request includes the encrypted seed pair.

The transports share the wallet/protocol handler and module runtime. Both support the swidge protocol type, enforce RpcContext.allowedMethods, and enforce allowedModuleMethods for generic-module calls. JSON-RPC callModule parameters match CallModuleRequest, including its JSON-string args. Results use response.result.result; events arrive as moduleEvent notifications with params: { module, event, payload } and a decoded payload. See the JSON-RPC examples.

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?