Skip to main content

Crate cow_sdk_browser_wallet

Crate cow_sdk_browser_wallet 

Source
Expand description

§cow-sdk-browser-wallet

Browser-wallet integration for the CoW Protocol Rust SDK. Exposes typed EIP-1193 provider, signer, discovery, and session contracts for WASM consumers plus a deterministic mock transport for tests and review flows.

⚠️ Alpha — 0.1.0-alpha. Pre-release and not security-audited; the public API may change before 0.1.0. It is published as a pre-release, so Cargo selects it only when you opt in (cow-sdk-browser-wallet = "0.1.0-alpha.1"). Review it yourself before relying on it with real funds.

This crate is the browser-runtime leaf of the cow-rs package family. The public API stays Rust-native and typed; raw JavaScript payloads remain local to the crate. Most consumers reach this crate through the cow-sdk facade’s browser-wallet feature flag; depend on it directly when building a WASM integration that does not use the trading facade. Injected-wallet behavior is environment-sensitive: authorization prompts, provider inventory, and vendor-specific support are controlled by the browser runtime rather than normalized into universal SDK guarantees.

For TypeScript applications that already use viem, ethers, wagmi, or another JavaScript wallet stack, prefer cow-sdk-wasm. It exposes the SDK through typed callbacks and keeps JavaScript wallet objects outside Rust trait storage. This crate remains the Rust-native browser-wallet leaf.

Transaction submission through the browser wallet returns TransactionBroadcast with the hash accepted by the injected provider. Receipt observation is a separate provider lookup. When an EIP-1193 receipt is available, this crate populates TransactionReceipt fields for status, block, gas, sender, and recipient; absent optional fields remain empty, while present malformed fields fail closed with a typed browser-wallet error.

Typed-data signing consumes cow_sdk_core::TypedDataDomain directly; the cow struct emits the canonical EIP-1193 eth_signTypedData_v4 second-parameter wire shape through its own Serialize impl per ADR 0052, pinned by PROP-BWL-007 against parity/fixtures/signing/eth_sign_typed_data_request.json.

§What it provides

  • Typed EIP-1193 provider, signer, and session — Eip1193Provider (implements Provider + SigningProvider), Eip1193Signer (implements Signer), and WalletSession, usable by the trading crate like any other signer/provider.
  • Bounded injected-wallet discovery — EIP-6963 first with a window.ethereum fallback, never auto-selecting when more than one wallet is present (InjectedWalletDiscovery).
  • Typed chain management — add_chain / switch_chain / switch_or_add_chain with WalletChainParameters validation (http(s) URLs, non-empty names) before any RPC, and success confirmed against a refreshed session.
  • Origin-trust gating — anonymous (non-EIP-6963) providers must opt in via Eip1193ProviderBuilder::trusted_origin, or build() fails with UntrustedProviderOrigin.
  • Chain-bound signing — signer_for_chain revalidates the session chain and the typed-data domain chain before signing.
  • A deterministic mock transport — MockEip1193Transport, panic-free and scriptable, for tests and review without a browser.
  • Normalized RPC errors — raw JS codes map to typed variants (4001, 4900, 4901, 4902, -32601); a 4001 rejection round-trips as cow_sdk_core::UserRejection so the signing path can route it.

§Install

[dependencies]
cow-sdk-browser-wallet = "0.1.0-alpha.1"

Or enable the feature through the facade:

[dependencies]
cow-sdk = { version = "0.1.0-alpha.1", features = ["browser-wallet"] }

§Minimal example

use cow_sdk_browser_wallet::{BrowserWallet, MockEip1193Transport, Origin};

let transport = MockEip1193Transport::sepolia().with_label("example wallet");
let origin = Origin::new("test://example-wallet").expect("example origin must be valid");
let _wallet = BrowserWallet::from_trusted_transport(transport, origin)
    .expect("trusted example transport must build");

§Feature flags

FeatureDefaultEnables
tracingofftracing spans on BrowserWallet methods and origin-trust warnings.

§Where this fits

This is the Rust-native browser-runtime leaf. It exposes only the typed Eip1193Transport seam — raw JS payloads stay private — and no alloy_* type appears in its public API. Real discovery and detection exist only on wasm32; native builds compile (so tests link) but return empty/None. For TypeScript apps already on viem, ethers, or wagmi, prefer cow-sdk-wasm (published to npm); this crate is for Rust-in-browser (Yew, Leptos, Dioxus) integrations. Reach it through the cow-sdk facade’s browser-wallet feature as cow_sdk::browser_wallet.

§Where to next

§License

Licensed under GPL-3.0-or-later. See the workspace LICENSE file for the full text. Browser wallet integration for WASM consumers using typed EIP-1193 provider, signer, discovery, and session contracts.

This crate is the browser-runtime leaf of the SDK package family.

It exposes three support layers:

The public contract stays typed and Rust-native. Raw JavaScript payloads remain local to the crate, and this package does not add a generic wallet-RPC passthrough beyond the typed EIP-1193 transport seam it owns. Typed chain-management helpers confirm the refreshed wallet session chain before they report switch success.

Injected-wallet behavior remains environment-sensitive. Authorization prompts, provider inventory, extension timing, and vendor-specific support are controlled by the browser runtime and wallet extension rather than normalized into universal SDK guarantees.

§Dependency Posture

The typed EIP-1193 contract-call bridge inside provider uses the alloy-primitives, alloy-dyn-abi, and alloy-json-abi family for ABI encoding and decoding. That dependency choice, including the reviewed advisories the alloy toolchain transits, is tracked publicly in docs/audit/browser-wallet-alloy-dependency-audit.md. No alloy_* type appears in this crate’s public API; workspace-wide, alloy interop is confined to the explicit as_alloy/into_alloy/from_alloy accessors on the core domain newtypes, never leaked implicitly through a helper signature.

Re-exports§

pub use error::BrowserWalletError;
pub use error::RpcErrorPayload;
pub use events::EventLog;
pub use events::WalletEvent;
pub use events::WalletSession;
pub use mock::MockEip1193Transport;
pub use mock::MockRequestRecord;
pub use provider::Eip1193Provider;
pub use provider::Eip1193ProviderBuilder;
pub use provider::Eip1193Transport;
pub use provider::Origin;
pub use signer::Eip1193Signer;
pub use wallet::BrowserWallet;
pub use wallet::InjectedWalletDetectionOptions;
pub use wallet::InjectedWalletDiscovery;
pub use wallet::InjectedWalletDiscoverySource;
pub use wallet::InjectedWalletInfo;
pub use wallet::WalletChainChange;
pub use wallet::WalletChainChangeKind;
pub use wallet::WalletChainParameters;
pub use wallet::WalletNativeCurrency;

Modules§

error
Browser-wallet error and RPC failure types. Browser-wallet error types and RPC error normalization.
events
Session state, event-log types, and provider-driven session synchronization. Typed wallet session and event-log state.
js
Browser-runtime discovery and injected-provider transport bindings. Browser-only injected-provider discovery and runtime bindings.
mock
Deterministic mock transport used for tests, examples, and proof-oriented verification. Deterministic mock EIP-1193 transport used by tests, examples, and proof-oriented reviews.
provider
Typed EIP-1193 provider transport and Provider bridge. Typed EIP-1193 provider bridge and Provider implementation.
signer
Typed EIP-1193 signer and typed-data signing helpers. Typed EIP-1193 signer implementation for browser wallets.
wallet
Browser-wallet discovery, session, and typed chain-management entrypoints. Browser-wallet discovery, session, and typed chain-management entrypoints.

Traits§

Provider
Read-only provider boundary for browser wallets, native RPC adapters, and runtimes that expose chain data.
Signer
Signing boundary for wallets and runtimes.
SigningProvider
Signing-capable extension for provider implementations.