@1shotapi/ows-wallet-utils

Utilities for Branding Layer implementers to communicate with the Host Layer.

Built on postmate with a JSON-RPC-style callback protocol and Zod-validated EIP-1193 params.

Install

npm install @1shotapi/ows-wallet-utils zod

Quick start (Branding Layer)

import { OWSWallet } from "@1shotapi/ows-wallet-utils";
import { z } from "zod";

const wallet = await OWSWallet.create({
  eip1193: {
    async eth_requestAccounts() {
      return ["0xYourAddress"];
    },
    async personal_sign(params) {
      const [message] = params as [string, string];
      return "0x…";
    },
  },
  rpc: {
    getStatus: {
      handler: async () => ({ connected: true }),
    },
  },
});

// Or register before handshake:
const prepared = OWSWallet.prepare();
prepared.registerRpc(
  "customMethod",
  async (params) => ({ ok: true }),
  z.object({ foo: z.number() }),
);
await prepared.start();

Unregistered EIP-1193 methods respond with OwsUnimplementedError (-32601). Custom RPC methods must be registered via options.rpc or registerRpc() before start().

Analytics (Branding → Host)

Emit product events to the host over Postmate (ows:analytics). Extend OWSAnalyticsEvent so eventId, timestamp, and branded hostDomain are filled in super(...); add branding fields on the subclass.

import {
  DomainString,
  EVMAccountAddress,
  OWSAnalyticsEvent,
} from "@1shotapi/ows-types";
import { OWSWallet } from "@1shotapi/ows-wallet-utils";

class AccountCreatedEvent extends OWSAnalyticsEvent {
  constructor(
    hostDomain: DomainString,
    public readonly accountAddress: EVMAccountAddress,
  ) {
    super("AccountCreated", hostDomain);
  }
}

const wallet = await OWSWallet.create({ /* … */ });
wallet.analytics.emit(
  new AccountCreatedEvent(DomainString("app.example.com"), EVMAccountAddress("0x…")),
);

Debug logging

Enable console.debug traces for Postmate handshake and RPC traffic:

await OWSWallet.create({ debug: true, eip1193: { ... } });

Or in the browser console before the wallet loads:

localStorage.setItem("ows-wallet-utils:debug", "1");
// or: globalThis.OWS_WALLET_UTILS_DEBUG = true;

Protocol

• Host calls child.call(method, envelope) via Postmate
• Child emits ows:rpcCallback with { callId, success, result | error }
• Host-side OWSProxy sets iframe allow (WebAuthn, clipboard) before navigation — do not override after load

Exports

• OWSWallet — child-side Postmate model
• AnalyticsChildClient — Branding→Host analytics emit (wallet.analytics.emit)
• RpcHelper — EIP-1193 read methods + chain switching against JSON-RPC URLs
• EIP1193_PARAM_SCHEMAS, getEip1193ParamSchema — Zod validators for standard methods
• CredentialWalletRegistrar, CREDENTIAL_PARAM_SCHEMAS — credentials wire hooks (handlers still registered on OWSWallet.credentials)

For OID4 issuance/presentation orchestration, install the optional @1shotapi/ows-oid4 add-on (CredentialsHelper, HTTP clients).

Shared protocol types and errors live in @1shotapi/ows-types.

Related

| Package | Role | |---------|------| | @1shotapi/ows-provider | Host Layer OWSProxy + EIP-1193 | | @1shotapi/ows-signer-utils | Branding Layer ↔ Signing Layer | | @1shotapi/ows-oid4 | Optional credentials add-on |

License

MIT