Add a path for blockchain devs coming from other chains

Author: sirdeggen

docs/architecture/brc-100.md

@@ -41,8 +41,8 @@ On mobile, BSV Browser embeds the web app and exposes the same method surface th
 
 1. The app calls the same BRC-100 method.
 2. The browser WebView sends the request to native code over `postMessage`.
-3. The native wallet selects outputs and signs on the device.
-4. The wallet may use Wallet Infra, ARC, Chaintracks, or other services.
+3. The native wallet selects outputs from its local database and signs on the device.
+4. The wallet may still use network services such as ARC or Chaintracks for broadcast, headers, and proofs.
 5. The result returns to the web app through the bridge.
 
 The application does not need separate business logic for desktop and mobile if it stays on the BRC-100 interface.

docs/assets/diagrams/brc100-wallet-flows.svg

@@ -21,6 +21,9 @@ Browser app using a user's wallet?
 Backend agent with its own key?
   -> @bsv/simple/server
 
+Coming from another chain and want to build transactions explicitly?
+  -> @bsv/wallet-helper
+
 Wallet implementation or wallet infrastructure?
   -> @bsv/wallet-toolbox + BRC-100 spec
 
@@ -51,6 +54,22 @@ console.log(result.txid)
 
 The web app does not hold private keys. The wallet client finds an available substrate and forwards BRC-100 calls to the user's wallet application.
 
+## Transaction Builder
+
+Use `@bsv/wallet-helper` when you want to construct transactions directly, but you do not want to drop all the way into raw `WalletClient.createAction` and `signAction` calls.
+
+This is often the clearest starting point for developers coming from other blockchain stacks: you can think in terms of explicit transaction outputs, scripts, ordinals, metadata, inputs, and change, while the user's BRC-100 wallet still controls keys and signing.
+
+```bash
+npm install @bsv/wallet-helper
+```
+
+Read this with the BRC-100 method reference when you need to understand what the builder sends to the wallet:
+
+- [@bsv/wallet-helper](../packages/helpers/wallet-helper.md)
+- [`createAction`](../specs/brc-100-wallet.md#createaction)
+- [`signAction`](../specs/brc-100-wallet.md#signaction)
+
 ## Server Agent
 
 Use this for automated services, bots, funding agents, or test harnesses where the service owns a key.
@@ -115,6 +134,7 @@ Use the infrastructure docs when you need shared services rather than npm packag
 | What you're building | Start with | Usually adds |
 |----------------------|------------|--------------|
 | Browser app | `@bsv/simple/browser` | `@bsv/message-box-client`, overlays |
+| Transaction-building app | `@bsv/wallet-helper` | `@bsv/templates`, BRC-100 method reference |
 | Server agent | `@bsv/simple/server` | `@bsv/402-pay`, Message Box |
 | BRC-100 wallet | `@bsv/wallet-toolbox` | Wallet Infra, WAB, Chaintracks |
 | Protocol library | `@bsv/sdk` | Conformance vectors |

docs/get-started/choose-your-stack.md

@@ -23,7 +23,7 @@ BRC-100 is the wallet-to-application interface. Application code can ask for act
 Two common substrates use the same method surface:
 
 - **BSV Desktop**: a web app calls a wallet client; the request reaches a localhost wallet server; BSV Desktop selects outputs, signs locally, optionally uses Wallet Infra, and returns the result.
-- **BSV Browser**: the web app runs inside an embedded browser; the request crosses a postMessage bridge into the native mobile wallet; signing happens on-device and the result returns over the bridge.
+- **BSV Browser**: the web app runs inside an embedded browser; the request crosses a postMessage bridge into the native mobile wallet; wallet state comes from a local database, signing happens on-device, and the result returns over the bridge.
 
 For a method-level contract, link directly to [BRC-100 Wallet Interface](../specs/brc-100-wallet.md). For example: [`createAction`](../specs/brc-100-wallet.md#createaction), [`signAction`](../specs/brc-100-wallet.md#signaction), [`internalizeAction`](../specs/brc-100-wallet.md#internalizeaction), and [`listOutputs`](../specs/brc-100-wallet.md#listoutputs).
 

docs/get-started/concepts.md

@@ -22,6 +22,8 @@ npm install @bsv/simple
 
 Use `@bsv/sdk` directly only when you need protocol-level control over keys, scripts, transactions, BEEF, BUMP, or the raw BRC-100 `WalletClient`.
 
+If you are coming from another blockchain stack and want to build transactions explicitly, start with [`@bsv/wallet-helper`](../packages/helpers/wallet-helper.md). It is more technical than `@bsv/simple`, but easier to work with than direct `WalletClient.createAction` and `signAction` calls.
+
 ## Step 2: Connect to a User Wallet
 
 Browser apps use `@bsv/simple/browser`. Under the hood it creates a BRC-100 wallet client and discovers an available wallet substrate such as BSV Desktop over localhost or BSV Browser over a postMessage bridge.
@@ -100,6 +102,7 @@ Do not generate and discard a production private key at runtime. Persist it in y
 | Need | Read |
 |------|------|
 | Pick packages by use case | [Choose Your Stack](./choose-your-stack.md) |
+| Build explicit transactions with a wallet | [@bsv/wallet-helper](../packages/helpers/wallet-helper.md) |
 | Understand BEEF, wallets, overlays, and BRC-100 | [Key Concepts](./concepts.md) |
 | See every BRC-100 method shape | [BRC-100 Wallet Interface](../specs/brc-100-wallet.md) |
 | Build a wallet or wallet-like implementation | [@bsv/wallet-toolbox](../packages/wallet/wallet-toolbox.md) |

docs/get-started/index.md

@@ -28,6 +28,7 @@ This repository is the TypeScript reference stack for BSV application developmen
 | You are | Use first | Why |
 |---------|-----------|-----|
 | Web application developer | [`@bsv/simple/browser`](./get-started/index.md) | Connects to a local BRC-100 wallet without putting keys in app code. |
+| Developer coming from another chain | [`@bsv/wallet-helper`](./packages/helpers/wallet-helper.md) | Builds explicit transactions with a fluent builder while the wallet keeps keys and signing. |
 | Backend or automation developer | [`@bsv/simple/server`](./get-started/choose-your-stack.md#server-agent-automated-self-custodial) | Runs a self-custodial server wallet from a private key and storage endpoint. |
 | Wallet developer | [`@bsv/wallet-toolbox`](./packages/wallet/wallet-toolbox.md) | Reference components for building a BRC-100 wallet. |
 | Protocol engineer | [`@bsv/sdk`](./packages/sdk/bsv-sdk.md) | Core crypto, scripts, transactions, BEEF, BUMP, and wallet interface types. |
@@ -59,7 +60,7 @@ For raw BRC-100 work, use `WalletClient` from `@bsv/sdk` and call methods such a
 | Overlays | `@bsv/overlay`, `@bsv/overlay-express`, topics, discovery, GASP | Shared on-chain context, topic validation, lookup services, sync. |
 | Messaging | Message Box, Authsocket, Paymail | Store-and-forward messages, live authenticated channels, identity-based addressing. |
 | Middleware | Auth, HTTP 402, payment express | Express middleware for identity and payment-gated APIs. |
-| Helpers | `@bsv/simple`, templates, DID, wallet helper, amount utilities | Higher-level developer ergonomics on top of the core protocols. |
+| Helpers | `@bsv/simple`, `@bsv/wallet-helper`, templates, DID, amount utilities | Higher-level developer ergonomics, including wallet-aware app helpers and fluent transaction building. |
 
 ## Important References
 

docs/index.md

@@ -2,7 +2,7 @@
 id: domain-helpers
 title: Helpers
 kind: reference
-last_updated: "2026-04-28"
+last_updated: "2026-04-30"
 version: "n/a"
 last_verified: "2026-04-28"
 review_cadence_days: 90
@@ -19,7 +19,7 @@ Utility libraries and helper tools for common BSV operations. Includes high-leve
 | Package | Purpose |
 |---------|---------|
 | [@bsv/simple](simple.md) | High-level wallet API for browser and server — manage payments, tokens, inscriptions, DIDs, and credentials |
-| [@bsv/wallet-helper](wallet-helper.md) | Fluent transaction builder with BRC-29 derivation and ordinal support |
+| [@bsv/wallet-helper](wallet-helper.md) | Fluent transaction builder for explicit wallet-backed transactions, BRC-29 derivation, and ordinal support |
 | [@bsv/templates](templates.md) | Low-level script templates (OpReturn, MultiPushDrop, P2MSKH) with lock/unlock patterns |
 | [@bsv/did-client](did-client.md) | DID client for creating, revoking, and querying on-chain DIDs with overlay broadcast |
 | [@bsv/amountinator](amountinator.md) | Multi-currency converter (SATS↔BSV↔15+ fiat) with exchange rate caching |

docs/packages/helpers/index.md

@@ -6,8 +6,8 @@ domain: helpers
 version: "0.0.6"
 source_repo: "bsv-blockchain/wallet-helper"
 source_commit: "unknown"
-last_updated: "2026-04-28"
-last_verified: "2026-04-28"
+last_updated: "2026-04-30"
+last_verified: "2026-04-30"
 review_cadence_days: 30
 npm: "https://www.npmjs.com/package/@bsv/wallet-helper"
 repo: "https://github.com/bsv-blockchain/wallet-helper"
@@ -19,6 +19,10 @@ tags: [helpers, wallet, transaction-builder]
 
 > Fluent transaction builder and wallet-compatible script templates for BSV — construct multi-output transactions (P2PKH, ordinals, custom) with method chaining, BRC-29 key derivation, and no private key exposure.
 
+`@bsv/wallet-helper` is a good starting point for developers coming from other blockchain ecosystems who expect to build transactions explicitly. It gives you a transaction-builder shape for outputs, scripts, ordinals, metadata, inputs, and change, while still delegating keys and signing to a BRC-100 wallet.
+
+Use it when `@bsv/simple` feels too task-oriented, but raw `@bsv/sdk` `WalletClient.createAction` / `signAction` calls are more protocol surface than you want to handle directly.
+
 ## Install
 
 ```bash
@@ -110,6 +114,7 @@ const ordResult = await new TransactionBuilder(wallet, "Mint ordinal")
 
 ## When to use this
 
+- You are coming from another blockchain stack and want an explicit transaction-building workflow
 - Building transactions with method chaining
 - Creating complex multi-output transactions readably
 - Working with ordinals and inscriptions
@@ -143,7 +148,7 @@ const ordResult = await new TransactionBuilder(wallet, "Mint ordinal")
 
 - [@bsv/simple](simple.md) — High-level wallet operations
 - [@bsv/templates](templates.md) — Low-level script templates
-- [@bsv/sdk](https://github.com/bsv-blockchain/sdk-ts) — Core transaction building
+- [@bsv/sdk](../sdk/bsv-sdk.md) — Core primitives, raw transactions, and the BRC-100 `WalletClient`
 
 ## Reference