Add provider-backed public launch SDK helpers

Author: FlowmemoryAI

docs/CURRENT_STATE.md

@@ -16,7 +16,7 @@ A local/test Agent Bonds v1 accountability surface exists for objective off-chai
 
 On 2026-05-13 a small Base mainnet canary deployment was broadcast for V0 testing. It is documented in `docs/DEPLOYMENTS/2026-05-13-base-canary-v0.md`. A guarded Base mainnet canary reader now exists for those known canary addresses and small explicit block ranges. This is not a production launch and does not change the production/mainnet-readiness guardrails.
 
-On 2026-05-21 the repo gained a public-agent local/test stack: shared `BaseOnchainAgentMemory` runtime integration, public agent class/tool/profile/lineage/fuel/bond/receipt contracts, `AgentFactory`, swarm policy/registry/budget/factory contracts, deterministic public launch helpers, control-plane and SDK/CLI discovery/preview methods, direct calldata builders for `AgentFactory.launchAgent(...)` and `SwarmFactory.createSwarm(...)`, dashboard projection, Foundry tests, a local Foundry e2e script, and Base Sepolia public-agent deployment/readback tooling with a configured public testnet deployer plan. This is public for review and local/testnet experimentation only; it is not a production launch or audited runtime.
+On 2026-05-21 the repo gained a public-agent local/test stack: shared `BaseOnchainAgentMemory` runtime integration, public agent class/tool/profile/lineage/fuel/bond/receipt contracts, `AgentFactory`, swarm policy/registry/budget/factory contracts, deterministic public launch helpers, control-plane and SDK/CLI discovery/preview methods, direct calldata builders plus EIP-1193 provider submission/receipt-decoding helpers for `AgentFactory.launchAgent(...)` and `SwarmFactory.createSwarm(...)`, dashboard projection, Foundry tests, a local Foundry e2e script, and Base Sepolia public-agent deployment/readback tooling with a configured public testnet deployer plan. This is public for review and local/testnet experimentation only; it is not a production launch or audited runtime.
 
 The public-facing app story includes the mobile operator layer. The shared dashboard surface is packaged as browser/desktop and a committed Android Capacitor shell, while iOS remains an explicitly documented product track until an Xcode project and CI lane are added. Mobile is positioned as the always-available operator console for Agent Bonds, receipts, recourse, wallet/budget state, public-agent monitoring, and future alerting.
 
@@ -86,7 +86,7 @@ Public-agent stack:
 - Shared `BaseOnchainAgentMemory` runtime integration exists.
 - Public agent class/tool/profile/lineage/fuel/bond/receipt contracts and `AgentFactory` exist.
 - Swarm policy/registry/budget/factory contracts exist.
-- Deterministic public launch helpers, control-plane discovery/preview methods, SDK/CLI smoke lanes, direct calldata builders, dashboard projection, Foundry tests, a local Foundry e2e script, and Base Sepolia public-agent deploy/readback tooling exist.
+- Deterministic public launch helpers, control-plane discovery/preview methods, SDK/CLI smoke lanes, direct calldata builders plus EIP-1193 provider submission/receipt-decoding helpers, dashboard projection, Foundry tests, a local Foundry e2e script, and Base Sepolia public-agent deploy/readback tooling exist.
 - This is public for review and local/testnet experimentation only; it is not a production launch or audited runtime.
 
 Mobile operator layer:

docs/PUBLIC_AGENT_NETWORK_RELEASE.md

@@ -16,10 +16,10 @@ The current public-agent network stack includes:
 - launch-bond escrow and memory-fuel vault flows;
 - public launch preview, launch intent, discovery, and prototype projection methods in the control-plane;
 - public agent class/tool helpers and deterministic launch-root builders in `services/flowmemory`;
-- contract-aligned launch digest helpers plus direct calldata builders for SDK and signer integrations;
+- contract-aligned launch digest helpers, direct calldata builders, EIP-712 typed-data signing requests, EIP-1193 provider submission helpers, receipt polling, and event decoding for SDK and signer integrations;
 - swarm policy, identity, membership, lifecycle, factory, and budget vault contracts;
 - public swarm preview, launch intent, replay, prototype projection methods, and direct create-call builders;
-- public SDK and CLI wrappers for discovery, public launch/swarm projections, and local CLI smoke;
+- public SDK and CLI wrappers for discovery, public launch/swarm projections, direct contract preparation/submission helpers, and local CLI smoke;
 - dashboard public-network view backed by deterministic local data;
 - Foundry tests for public contracts and a local script that exercises agent launch plus swarm budget lifecycle;
 - Base Sepolia public-agent deployment, source-verification, and bounded event-readback tooling with a configured public testnet deployer plan in `fixtures/deployments/public-agent-network-base-sepolia-plan.json`.

docs/PUBLIC_AGENT_NETWORK_TECHNICAL_GUIDE.md

@@ -103,11 +103,11 @@ The open swarm-born-agent work is tracked in issue #168.
 
 Public-agent methods include class/tool discovery, launch preview, launch intent, prototype launch record, and discovery projection. Public-swarm methods include class discovery, launch preview, prototype swarm record, and replay projection.
 
-Current methods are local/control-plane projections. The public helper layer also includes direct calldata builders for `AgentFactory.launchAgent(...)` and `SwarmFactory.createSwarm(...)`, so a signer or wallet can prepare contract-ready transaction data without accepting raw secrets into the repo.
+Current methods are local/control-plane projections. The public helper layer also includes direct calldata builders for `AgentFactory.launchAgent(...)` and `SwarmFactory.createSwarm(...)`, EIP-712 typed-data request builders for owner signatures, EIP-1193 provider-backed submission helpers, receipt polling, and public-agent/swarm event decoding. These helpers are designed for wallet/provider integrations; they do not accept raw private keys by default.
 
 ### Public SDK and CLI
 
-The public SDK/CLI surface wraps public-agent and swarm commands for class/tool discovery, launch preview, launch intent, launch projection, agent discovery, swarm projection, swarm replay, and direct local/test contract-call preparation. External users should exercise it through `npm run public:test:quick` and `npm run public:test:cli` rather than older internal command names.
+The public SDK/CLI surface wraps public-agent and swarm commands for class/tool discovery, launch preview, launch intent, launch projection, agent discovery, swarm projection, swarm replay, and direct local/test contract-call preparation. External users should exercise it through `npm run public:test:quick` and `npm run public:test:cli` rather than older internal command names. Direct contract submission should use an external wallet or provider implementing `request({ method, params })`; raw deployer keys, RPC credentials, and wallet secrets stay outside the SDK and outside Git.
 
 ### Agent Memory SDK
 

docs/PUBLIC_RELEASE_GAPS.md

@@ -36,15 +36,14 @@ Missing work:
 
 Tracking issue: https://github.com/FlowmemoryAI/FlowMemory/issues/166
 
-Current state: the public helper layer exposes control-plane wrappers, FlowMemory helpers produce deterministic roots plus contract-aligned launch hashes, and direct calldata builders now exist for `AgentFactory.launchAgent` and `SwarmFactory.createSwarm`. Direct transaction submission is not yet a complete SDK surface.
+Current state: the public helper layer exposes control-plane wrappers, deterministic roots, contract-aligned launch hashes, direct calldata builders, EIP-712 typed-data signing requests, EIP-1193 provider-backed submission helpers, transaction receipt polling, and public-agent/swarm receipt event decoding. The SDK does not accept raw private keys by default.
 
 Missing work:
 
-- signer-provider abstraction that does not accept raw secrets by default;
-- provider-backed submission for `AgentFactory.launchAgent`;
-- provider-backed submission for `SwarmFactory.createSwarm`;
-- receipt polling and event decoding;
-- test coverage against local Anvil broadcast logs.
+- local Anvil SDK e2e that prepares, signs through an external provider, submits `AgentFactory.launchAgent`, waits for the receipt, and checks decoded launch/fuel/bond events;
+- local Anvil SDK e2e that submits `SwarmFactory.createSwarm`, waits for the receipt, and checks decoded swarm/budget events;
+- negative local Anvil coverage for nonce replay and bad class/toolset through the direct SDK lane;
+- public evidence from those local Anvil broadcast logs.
 
 ### 4. Public-network dashboard live data
 

services/flowmemory-sdk/src/index.ts

@@ -8,12 +8,29 @@ export {
 } from "./client.ts";
 export { redactFlowMemoryText, redactJsonValue } from "./redact.ts";
 export {
+  PUBLIC_AGENT_CONTRACT_EVENT_TOPICS,
   buildPublicAgentLaunchTransaction,
+  buildPublicAgentLaunchTypedData,
   buildPublicSwarmCreateTransaction,
+  decodePublicContractReceipt,
+  signPublicAgentLaunchIntent,
+  submitPreparedContractTransaction,
+  submitPublicAgentLaunchTransaction,
+  submitPublicSwarmCreateTransaction,
+  waitForTransactionReceipt,
+  type DecodedPublicContractEvent,
+  type DecodedPublicContractReceipt,
+  type Eip1193Provider,
+  type EvmTransactionReceipt,
+  type EvmTransactionReceiptLog,
   type PreparedContractTransaction,
   type PreparedPublicAgentLaunchTransaction,
   type PreparedPublicSwarmCreateTransaction,
   type PublicAgentLaunchPaymentInput,
+  type PublicAgentLaunchTypedData,
+  type PublicAgentLaunchTypedDataRequest,
   type PublicSwarmMemberInput,
   type PublicSwarmMemberType,
+  type SubmittedContractTransaction,
+  type WaitForTransactionReceiptOptions,
 } from "./public-contracts.ts";