@effectstream/wallets 0.100.14 → 0.100.16

package/README.md

@@ -1 +1,120 @@
-# Effectstream Wallets
+# @effectstream/wallets
+
+Browser wallet connectors and the runtime client an EffectStream
+frontend uses to log in, sign batcher messages, send transactions, and
+wait for them to be processed. Spans MetaMask (and any EVM-injected
+wallet), Cardano (CIP-30), Midnight, Mina, Polkadot, Algorand, and
+Avail.
+
+- Browser wallet connectors plus the runtime client a frontend uses to log in, sign, and submit.
+- Spans MetaMask + injected EVM, Cardano (CIP-30), Midnight, Mina, Polkadot, Algorand, Avail.
+- Used together with `@effectstream/crypto` (server-side verification).
+- High-level helpers `walletLogin` and `sendTransaction` hide the polling loop.
+
+## Install
+
+```bash
+bun add @effectstream/wallets
+# or
+npm install @effectstream/wallets
+```
+
+## Standalone usage
+
+The high-level path most apps use: log in with a wallet, then send a
+transaction through the batcher and wait until it lands in a block.
+
+```typescript
+import {
+  walletLogin,
+  WalletMode,
+  EffectstreamConfig,
+  sendTransaction,
+} from "@effectstream/wallets";
+
+const config = new EffectstreamConfig({ /* …chain/batcher URLs… */ });
+
+const wallet = await walletLogin({
+  config,
+  preference: { name: "MetaMask" },
+  mode: WalletMode.EvmInjected,
+});
+
+const result = await sendTransaction(wallet, "join|alice");
+// result.blockHeight === number once the batcher's submission landed
+```
+
+If you just want to discover available wallets:
+
+```typescript
+import { allInjectedWallets, WalletMode } from "@effectstream/wallets";
+
+const available = await allInjectedWallets({
+  signatureSupport: true,
+  transactionSupport: true,
+});
+const evmOptions = available[WalletMode.EvmInjected]; // [{ metadata, ... }, …]
+```
+
+> **Browser only.** This package depends on `window.ethereum`, the
+> Cardano CIP-30 API, etc. — it won't load in plain Node. Server-side
+> signature verification is `@effectstream/crypto`.
+
+## Inside EffectStream
+
+The client-side counterpart to `@effectstream/crypto`. Frontends
+connect a wallet, sign a batcher login or transaction, and POST it to
+the batcher HTTP endpoint (`@effectstream/batcher-sdk`). The node's
+state machine then verifies the signature with
+`CryptoManager.getCryptoManager(addressType)`. The runtime helpers
+exported here (`sendTransaction`, `waitForEffectstreamBlockProcessed`)
+hide the polling loop.
+
+## Key exports
+
+Login + signing:
+
+- `walletLogin(args)`: top-level helper that discovers, connects, and produces a signed batcher login.
+- `EffectstreamConfig`: runtime config (chain URLs, batcher URL, ...) the helpers consume.
+- `signMessage(wallet, message)` — sign an arbitrary message with the connected wallet.
+
+Sending transactions:
+
+- `sendTransaction(wallet, conciseInput, opts?)`: submit through the batcher and (by default) wait for processing.
+- `sendBatcherTransaction(...)`: explicit batcher submission.
+- `sendSelfSequencedTransaction(...)` bypasses the batcher.
+- `waitForEffectstreamBlockProcessed(...)` — block-height poller used by the above.
+
+Wallet discovery / identification:
+
+- `WalletMode`: enum of `EvmInjected`, `EvmEthers`, `Midnight`, `Cardano`, `Polkadot`, `Algorand`, `Mina`, `AvailJs`.
+- `WalletNameMap`: `Record<WalletMode, string>` for display.
+- `allInjectedWallets(config)` lists installed wallets in the browser.
+- `getAddressType(walletMode)` maps a `WalletMode` to its `@effectstream/utils` `AddressType`.
+
+Types:
+
+- `Wallet`: handle returned by `walletLogin`, used by send/sign helpers.
+- `UserSignature`, `Hash`, `BatcherPostResponse`, `BatcherTrackResponse`, `PostDataResponse`, `PostDataResponseAsync`, `SignFunction`.
+
+Lower-level connector machinery (used internally; export surface is
+stable but rarely needed in app code): `connectInjectedWallet`,
+`WalletModeMap`, `IProvider`, `IConnector`, `IInjectedConnector`,
+`InjectionPreference`.
+
+## Examples
+
+Runnable: [`src/utils.test.ts`](./src/utils.test.ts) and
+[`test/examples.test.ts`](./test/examples.test.ts).
+
+Real-world usage in templates (each imports `walletLogin`, `WalletMode`,
+`EffectstreamConfig`, `sendTransaction`):
+
+- [`templates/chess-v2/`](https://github.com/effectstream/effectstream/tree/main/templates/chess-v2)
+- [`templates/evm-midnight-v2/`](https://github.com/effectstream/effectstream/tree/main/templates/evm-midnight-v2)
+- [`templates/shinkai-v2/`](https://github.com/effectstream/effectstream/tree/main/templates/shinkai-v2)
+
+## Links
+
+- Docs: https://effectstream.github.io/docs/packages/sdk/wallets
+- Source: https://github.com/effectstream/effectstream/tree/main/packages/effectstream-sdk/wallets

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effectstream/wallets",
-  "version": "0.100.14",
+  "version": "0.100.16",
   "license": "MIT",
   "homepage": "https://effectstream.github.io/docs/",
   "repository": {
@@ -13,10 +13,10 @@
   },
   "exports": "./src/mod.ts",
   "dependencies": {
-    "@effectstream/concise": "0.100.14",
-    "@effectstream/crypto": "0.100.14",
-    "@effectstream/event-client": "0.100.14",
-    "@effectstream/utils": "0.100.14",
+    "@effectstream/concise": "0.100.16",
+    "@effectstream/crypto": "0.100.16",
+    "@effectstream/event-client": "0.100.16",
+    "@effectstream/utils": "0.100.16",
     "@aurowallet/mina-provider": "^1.0.12",
     "@metamask/providers": "^22.1.0",
     "@midnight-ntwrk/dapp-connector-api": "4.0.1",

package/src/effectstream.ts

@@ -15,7 +15,14 @@ import { BuiltinEvents, EventManager } from "@effectstream/event-client";
  * communication. It sets up the location of the Effectstream L2 Contact.
  */
 export class EffectstreamConfig {
-  public appName: string;
+  /**
+   * Security namespace string the user wallet signs into every batched message.
+   * Must match the server's `setSecurityNamespace(...)` (or, when the server uses
+   * a transition object, one of its `read.prefixes`) for the primitive's
+   * re-verification to admit the input. `undefined` / `""` means no namespace
+   * (legacy null-prefixed signing).
+   */
+  public securityNamespace: string | null;
   public effectstreamL2SyncProtocolName: string;
   public effectstreamL2ContractAddress: EvmAddress;
   public effectstreamL2Abi: AbiItem[];
@@ -26,7 +33,7 @@ export class EffectstreamConfig {
   public preferBatchedMode: boolean = false;
 
   constructor(
-    appName: string | undefined,
+    securityNamespace: string | undefined,
     effectstreamL2SyncProtocolName: string,
     effectstreamL2ContractAddress: EvmAddress,
     effectstreamL2Chain: Chain,
@@ -34,7 +41,9 @@ export class EffectstreamConfig {
     batcherURL: string | undefined,
     preferBatchedMode: boolean = false,
   ) {
-    this.appName = appName ?? "";
+    this.securityNamespace = securityNamespace && securityNamespace.length > 0
+      ? securityNamespace
+      : null;
 
     this.effectstreamL2SyncProtocolName = effectstreamL2SyncProtocolName;
     this.effectstreamL2ContractAddress = effectstreamL2ContractAddress;
@@ -338,7 +347,7 @@ export async function sendBatcherTransaction(
   const timestamp = Date.now().toString();
   const signature = await wallet.provider.signMessage(
     createMessageForBatcher(
-      effectstreamConfig.appName,
+      effectstreamConfig.securityNamespace,
       timestamp,
       wallet.provider.getAddress().address,
       wallet.provider.getAddress().type,

package/test/examples.test.ts

@@ -0,0 +1,62 @@
+// Examples for the README. Wallets is browser-only — so we exercise the
+// public API through a mock IInjectedConnector, the same pattern as
+// src/utils.test.ts.
+
+import { test, expect } from "bun:test";
+import { connectInjectedWallet } from "../src/utils.ts";
+import { WalletMode, WalletNameMap } from "../src/mod.ts";
+import type { IInjectedConnector, IProvider } from "../src/IProvider.ts";
+import { AddressType } from "@effectstream/utils";
+
+const MOCK_ADDRESS = "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd";
+const MOCK_METADATA = {
+  name: "MockWallet",
+  displayName: "Mock Wallet",
+  icon: "",
+  version: "1.0",
+};
+
+const mockProvider = (): IProvider<unknown> => ({
+  getConnection: () => ({ metadata: MOCK_METADATA, api: {} }),
+  getAddress: () => ({ type: AddressType.EVM, address: MOCK_ADDRESS }),
+  signMessage: async () => "0xsignedmessage",
+});
+
+const mockConnector = (): IInjectedConnector<unknown> => ({
+  connectSimple: async () => mockProvider(),
+  connectNamed: async (_name: string) => mockProvider(),
+  connectExternal: async () => mockProvider(),
+});
+
+test("README: WalletNameMap covers every WalletMode", () => {
+  for (
+    const mode of [
+      WalletMode.EvmInjected,
+      WalletMode.EvmEthers,
+      WalletMode.Midnight,
+      WalletMode.Cardano,
+      WalletMode.Polkadot,
+      WalletMode.Algorand,
+      WalletMode.Mina,
+      WalletMode.AvailJs,
+    ]
+  ) {
+    expect(typeof WalletNameMap[mode]).toBe("string");
+    expect(WalletNameMap[mode].length).toBeGreaterThan(0);
+  }
+});
+
+test("README: connectInjectedWallet returns an IProvider with address + sign", async () => {
+  const provider = await connectInjectedWallet(
+    "EVM",
+    { name: MOCK_METADATA.name },
+    mockConnector(),
+  );
+
+  const { type, address } = provider.getAddress();
+  expect(type).toBe(AddressType.EVM);
+  expect(address).toBe(MOCK_ADDRESS);
+
+  const signature = await provider.signMessage("Sign in 2026-05-14");
+  expect(signature).toBe("0xsignedmessage");
+});