feat(runner): add MiniappRunner for the Circles miniapps host

packages/runner/README.md

@@ -4,7 +4,7 @@ Safe multisig wallet integration for executing blockchain operations with the Ci
 
 ## Overview
 
-This package provides the `SafeContractRunner` implementation for executing transactions through Safe multisig wallets. It handles transaction batching, signing, and confirmation, making it easy to interact with Circles protocol using Safe wallets.
+This package provides the `SafeContractRunner`, `SafeBrowserRunner`, and `MiniappRunner` implementations for executing transactions. `SafeContractRunner` covers server-side use with a private key, `SafeBrowserRunner` wraps an EIP-1193 wallet extension, and `MiniappRunner` adapts the Circles miniapps iframe host's `sendTransactions` bridge to the SDK's `ContractRunner` interface so embedded mini-apps can use `core.hubV2.*` and the rest of the typed SDK without hand-rolling calldata.
 
 ## Installation
 
@@ -59,6 +59,54 @@ const batchReceipt = await runner.sendTransaction([
 ]);
 ```
 
+### MiniappRunner
+
+The `MiniappRunner` adapts the Circles miniapps host (`circles.gnosis.io/playground` or any other embedder) to the `ContractRunner` interface. Use it inside a mini-app, where the user's wallet lives in the parent frame and the host exposes a `sendTransactions(txs)` bridge instead of a direct EIP-1193 provider.
+
+```typescript
+import { createPublicClient, http } from 'viem';
+import { gnosis } from 'viem/chains';
+import {
+  onWalletChange,
+  sendTransactions,
+} from '@aboutcircles/miniapp-sdk';
+import { MiniappRunner } from '@aboutcircles/sdk-runner';
+import { Sdk } from '@aboutcircles/sdk';
+import { circlesConfig } from '@aboutcircles/sdk-utils';
+
+const publicClient = createPublicClient({
+  chain: gnosis,
+  transport: http('https://rpc.gnosischain.com'),
+});
+
+onWalletChange(async (address) => {
+  if (!address) return;
+  const runner = new MiniappRunner(publicClient, sendTransactions, address);
+  const sdk = new Sdk(circlesConfig[100], runner);
+
+  // Every Circles primitive now goes through the typed SDK wrappers
+  // — no hand-rolled calldata anywhere in your mini-app.
+  const avatar = await sdk.getAvatar(address);
+  await avatar.transfer.direct('0xRecipient', BigInt(1e18));
+});
+```
+
+Like `SafeBrowserRunner`, `MiniappRunner` exposes a static `create()` factory if you prefer a one-step setup:
+
+```typescript
+import { chains, MiniappRunner } from '@aboutcircles/sdk-runner';
+import { sendTransactions } from '@aboutcircles/miniapp-sdk';
+
+const runner = await MiniappRunner.create(
+  'https://rpc.gnosischain.com',
+  sendTransactions,
+  chains.gnosis,
+  viewerAddress,
+);
+```
+
+The `sendTransactions` function is passed in (not imported by `sdk-runner`) so this package stays free of a hard dependency on `@aboutcircles/miniapp-sdk` — that decoupling also makes the runner trivial to unit-test with a mock host.
+
 ## Features
 
 - **Transaction Confirmation**: Automatically waits for transactions to be mined
@@ -101,6 +149,29 @@ class SafeContractRunner implements ContractRunner {
 }
 ```
 
+### MiniappRunner
+
+```typescript
+class MiniappRunner implements ContractRunner {
+  constructor(
+    publicClient: PublicClient,
+    sendTransactions: MiniappSendTransactions,
+    address?: Address,
+  );
+
+  static create(
+    rpcUrl: string,
+    sendTransactions: MiniappSendTransactions,
+    chain: ChainLike,
+    address?: Address,
+  ): Promise<MiniappRunner>;
+
+  init(address?: Address): Promise<void>;
+  sendTransaction(txs: TransactionRequest[]): Promise<TransactionReceipt>;
+  sendBatchTransaction(): MiniappBatchRun;
+}
+```
+
 ## License
 
 MIT

packages/runner/src/index.ts

@@ -13,6 +13,13 @@ export { SafeContractRunner, SafeBatchRun } from './safe-runner.js';
 // Safe Browser Runner (client-side with Web3 wallet)
 export { SafeBrowserRunner, SafeBrowserBatchRun } from './safe-browser-runner.js';
 
+// Miniapp Runner (client-side embedded in the Circles miniapps iframe host)
+export { MiniappRunner, MiniappBatchRun } from './miniapp-runner.js';
+export type {
+  MiniappHostTransaction,
+  MiniappSendTransactions,
+} from './miniapp-runner.js';
+
 // Chain configuration types and presets
 export type { ChainConfig, ChainLike } from './chain-types';
 export { chains, asViemChain } from './chain-types';