From 14b5c8f7ce9c478dcb426c60bc8485ebcba225fc Mon Sep 17 00:00:00 2001
From: leo1987820 <leo1987820@gmail.com>
Date: Thu, 25 Jun 2026 03:06:57 +0800
Subject: [PATCH 1/2] docs: expand README quickstart examples

---
 README.md | 339 ++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 228 insertions(+), 111 deletions(-)

diff --git a/README.md b/README.md
index 5b6b305..8d51c65 100644
--- a/README.md
+++ b/README.md
@@ -1,186 +1,303 @@
-# 📦 TrustFlow SDK
+# TrustFlow SDK
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
+Type-safe TypeScript SDK for building escrow, milestone-payment, and dispute-resolution workflows on the TrustFlow Protocol.
 
-> **Type-safe TypeScript SDK for building gig-economy applications on the TrustFlow Protocol (Stellar/Soroban).**
+The SDK gives application developers a small set of clients and utilities for:
 
-The TrustFlow SDK provides a developer-friendly interface for interacting with TrustFlow smart contracts on the Stellar network. Build escrow systems, dispute resolution platforms, and decentralized freelance marketplaces with clean, type-safe APIs.
+- connecting to Stellar testnet or mainnet
+- creating and releasing escrows
+- building escrow parameters with validation-friendly helpers
+- listing backend-backed gig or escrow records
+- coordinating multi-signature release flows
+- formatting and validating Stellar addresses, amounts, and escrow IDs
 
----
-
-## ⚡ Quick Start
-
-### Installation
+## Installation
 
 ```bash
 npm install @trustflow/sdk
-# or
+```
+
+```bash
 yarn add @trustflow/sdk
 ```
 
-### Basic Usage
+## Requirements
+
+- Node.js 18 or newer
+- A deployed TrustFlow Soroban contract ID
+- Stellar accounts funded on the network you use
+- Optional TrustFlow backend URL and API key for APIs such as `getGigs`
+
+## Environment
+
+Create a local `.env` file or export these values in your runtime:
+
+```bash
+TRUSTFLOW_CONTRACT_ID=CCONTRACT...
+TRUSTFLOW_NETWORK=TESTNET
+TRUSTFLOW_API_BASE_URL=https://api.example.com
+TRUSTFLOW_API_KEY=dev-api-key
+```
+
+`TRUSTFLOW_NETWORK` should be `TESTNET` or `MAINNET`.
+
+## Connect To Stellar
+
+Use `TrustFlowClient` when your app needs network configuration, Horizon access, balance checks, or connection validation.
 
 ```typescript
 import { TrustFlowClient } from '@trustflow/sdk';
-import { createEscrow } from '@trustflow/sdk/escrow';
 
-// Initialize client
 const client = new TrustFlowClient({
   contractId: process.env.TRUSTFLOW_CONTRACT_ID!,
   network: 'TESTNET',
+  apiBaseUrl: process.env.TRUSTFLOW_API_BASE_URL,
+  apiKey: process.env.TRUSTFLOW_API_KEY,
 });
 
 await client.connect();
 
-// Create an escrow
-const escrow = await createEscrow(client, {
-  sender: 'GDEPOSITOR...',
-  recipient: 'GBENEFICIARY...',
-  amountStroops: '1000000',
-  durationBlocks: 17280,
-  metadata: { orderId: 'ORD-001' },
+console.log(client.getConfig());
+console.log('Connected:', client.isConnected());
+```
+
+## Create And Fund An Escrow
+
+`TrustFlowEscrowClient` wraps escrow operations. Use `EscrowBuilder` when you want chainable parameter construction before calling `createEscrow`.
+
+```typescript
+import { EscrowBuilder, TrustFlowEscrowClient } from '@trustflow/sdk';
+import { Networks } from '@stellar/stellar-sdk';
+
+const escrowClient = new TrustFlowEscrowClient({
+  contractId: process.env.TRUSTFLOW_CONTRACT_ID!,
+  network: 'TESTNET',
+  rpcUrl: 'https://soroban-testnet.stellar.org',
+  networkPassphrase: Networks.TESTNET,
+  apiBaseUrl: process.env.TRUSTFLOW_API_BASE_URL,
+  apiKey: process.env.TRUSTFLOW_API_KEY,
 });
 
-console.log('Escrow created:', escrow.id);
+const escrowParams = new EscrowBuilder()
+  .setDepositor('GDEPOSITOR...')
+  .setBeneficiary('GBENEFICIARY...')
+  .setAmount('100')
+  .setDeadline(17_280)
+  .build();
+
+const created = await escrowClient.createEscrow(escrowParams);
+
+if (!created.ok) {
+  throw new Error(created.error);
+}
+
+console.log('Escrow ID:', created.data.escrowId);
+console.log('Funding transaction:', created.data.txHash);
 ```
 
-See [examples/](./examples/) for more complete examples.
+The current escrow client returns an `SDKResult<T>` object, so callers should check `result.ok` before reading `result.data`.
 
-### Multi-Sig Escrow (M-of-N)
+## Release Funds
 
-Collect signatures from multiple approvers before a release is broadcast:
+Release an escrow by passing the escrow ID and the signer or releaser address.
 
 ```typescript
-import { MultiSigEscrowClient } from '@trustflow/sdk';
+import { TrustFlowEscrowClient } from '@trustflow/sdk';
 import { Networks } from '@stellar/stellar-sdk';
 
-const client = new MultiSigEscrowClient({
+const escrowClient = new TrustFlowEscrowClient({
   contractId: process.env.TRUSTFLOW_CONTRACT_ID!,
   network: 'TESTNET',
   rpcUrl: 'https://soroban-testnet.stellar.org',
   networkPassphrase: Networks.TESTNET,
 });
 
-// Register a 2-of-2 release operation
-const { data: { operationId } } = client.initMultiSigOperation({
-  escrowId: 'esc-42',
-  signers: [APPROVER_A, APPROVER_B],
-  threshold: 2,
-  operationType: 'release',
-  unsignedXdr: UNSIGNED_RELEASE_XDR,
-  networkPassphrase: Networks.TESTNET,
-});
+const released = await escrowClient.releaseEscrow('esc-123', 'GDEPOSITOR...');
 
-// Each approver submits their signed XDR independently
-client.addSignature({ operationId, signerAddress: APPROVER_A, signedXdr: SIGNED_XDR_A });
-client.addSignature({ operationId, signerAddress: APPROVER_B, signedXdr: SIGNED_XDR_B });
+if (!released.ok) {
+  throw new Error(released.error);
+}
 
-// Broadcast once threshold is met
-const result = await client.submitWhenReady(operationId, 'https://horizon-testnet.stellar.org');
-console.log('Released! tx:', result.data?.txHash);
+console.log('Release transaction:', released.data.txHash);
 ```
 
-See [examples/multisig-escrow.ts](./examples/multisig-escrow.ts) for the full walkthrough.
-
----
+## List Gigs With Pagination
 
-## ✨ Features
+`getGigs` is backed by the TrustFlow API, so `apiBaseUrl` is required. Pagination is cursor-based.
 
-### Current Capabilities
+```typescript
+import { TrustFlowEscrowClient } from '@trustflow/sdk';
+import { Networks } from '@stellar/stellar-sdk';
 
-- **🔐 Escrow Management**: Create, fund, release, and monitor escrows
-- **✍️ Multi-Sig Escrows**: M-of-N signature collection for shared backend Escrows via `MultiSigEscrowClient`
-- **⚖️ Dispute Resolution**: Raise and track disputes with on-chain governance
-- **🔑 Wallet Integration**: Built-in support for Freighter and Albedo wallets
-- **📊 Event Monitoring**: Real-time escrow state change tracking
-- **🛡️ Type Safety**: Full TypeScript support with Zod validation schemas
-- **🧪 Test Coverage**: Comprehensive Jest test suite
+const escrowClient = new TrustFlowEscrowClient({
+  contractId: process.env.TRUSTFLOW_CONTRACT_ID!,
+  network: 'TESTNET',
+  rpcUrl: 'https://soroban-testnet.stellar.org',
+  networkPassphrase: Networks.TESTNET,
+  apiBaseUrl: process.env.TRUSTFLOW_API_BASE_URL,
+  apiKey: process.env.TRUSTFLOW_API_KEY,
+});
 
-### Architecture Highlights
+let cursor: string | undefined;
 
-- **Result Types**: No thrown exceptions in public APIs - all errors returned as `SDKResult<T>`
-- **Immutable Builders**: Fluent APIs like `EscrowBuilder` for parameter construction
-- **Network Agnostic**: Easily switch between Testnet and Mainnet
-- **Pure Utilities**: Side-effect-free helper functions for formatting and validation
+do {
+  const page = await escrowClient.getGigs({
+    cursor,
+    limit: 20,
+    status: 'active',
+    depositor: 'GDEPOSITOR...',
+  });
 
-Read more in [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)
+  if (!page.ok) {
+    throw new Error(page.error);
+  }
 
----
+  for (const gig of page.data.data) {
+    console.log(gig.id, gig.status);
+  }
 
-## 📚 Documentation
+  cursor = page.data.nextCursor ?? undefined;
+} while (cursor);
+```
 
-- **[Quick Start Guide](./docs/QUICKSTART.md)** - Get up and running in 5 minutes
-- **[API Reference](./docs/API.md)** - Complete API documentation
-- **[Architecture](./docs/ARCHITECTURE.md)** - Design principles and module structure
-- **[Examples](./examples/)** - Working code examples for common use cases
+## Multi-Signature Escrow Release
 
----
+`MultiSigEscrowClient` coordinates M-of-N signature collection for release, cancel, or dispute operations.
 
-## 🗺️ Roadmap
+```typescript
+import { MultiSigEscrowClient } from '@trustflow/sdk';
+import { Networks } from '@stellar/stellar-sdk';
 
-The SDK is under active development. Here's what's coming:
+const multiSig = new MultiSigEscrowClient({
+  contractId: process.env.TRUSTFLOW_CONTRACT_ID!,
+  network: 'TESTNET',
+  rpcUrl: 'https://soroban-testnet.stellar.org',
+  networkPassphrase: Networks.TESTNET,
+});
 
-### In Progress
-- [ ] Tsup bundler configuration for ESM/CJS exports
-- [ ] NPM publishing pipeline with provenance
-- [ ] Simulation wrappers for transaction cost estimation
-- [ ] Auto-retry logic for RPC endpoints
+const init = multiSig.initMultiSigOperation({
+  escrowId: 'esc-123',
+  signers: ['GAPPROVERA...', 'GAPPROVERB...'],
+  threshold: 2,
+  operationType: 'release',
+  unsignedXdr: 'AAAA...',
+  networkPassphrase: Networks.TESTNET,
+});
 
-### Planned Features
-- [x] Multi-signature support for corporate escrows
-- [ ] IPFS storage helpers for file uploads
-- [ ] Pagination support for high-volume queries
-- [ ] Event parsing utilities for XDR decoding
-- [ ] Juror voting system integration
+if (!init.ok) {
+  throw new Error(init.error);
+}
 
-See our [GitHub Issues](https://github.com/trustflow-protocol/trustflow-sdk/issues) for detailed progress tracking.
+multiSig.addSignature({
+  operationId: init.data.operationId,
+  signerAddress: 'GAPPROVERA...',
+  signedXdr: 'AAAA-signed-by-a...',
+});
 
----
+multiSig.addSignature({
+  operationId: init.data.operationId,
+  signerAddress: 'GAPPROVERB...',
+  signedXdr: 'AAAA-signed-by-b...',
+});
 
-## 🤝 Contributing
+const submitted = await multiSig.submitWhenReady(
+  init.data.operationId,
+  'https://horizon-testnet.stellar.org',
+);
 
-We welcome contributions! To get started:
+if (submitted.ok) {
+  console.log('Submitted transaction:', submitted.data.txHash);
+}
+```
 
-1. Fork the repository
-2. Install dependencies: `npm install`
-3. Run tests: `npm test`
-4. Submit a PR
+See `examples/multisig-escrow.ts` for a fuller walkthrough.
 
-Please ensure:
-- Tests pass (`npm test`)
-- Linting passes (`npm run lint`)
-- Code is formatted (`npm run format`)
+## Utility Helpers
 
-Check [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines.
+```typescript
+import {
+  assertStellarAddress,
+  isValidEscrowId,
+  isValidXLMAmount,
+  stroopsToXLM,
+  truncateAddress,
+  xlmToStroops,
+} from '@trustflow/sdk';
+
+assertStellarAddress('GDEPOSITOR...', 'depositor');
+
+const stroops = xlmToStroops('10.5');
+console.log(stroops.toString());
+console.log(stroopsToXLM(stroops));
+console.log(truncateAddress('GDEPOSITOR...'));
+console.log(isValidXLMAmount('10.5'));
+console.log(isValidEscrowId('esc-123'));
+```
 
----
+## Error Handling
 
-## 🔒 Security
+The SDK uses two public error styles:
 
-- **Strict Linting**: ESLint strict mode enforced across the codebase
-- **Input Validation**: All parameters validated with Zod schemas
-- **Type Safety**: TypeScript strict mode prevents runtime errors
-- **Test Coverage**: Critical paths covered by Jest integration tests
+- `SDKResult<T>` for escrow clients, where callers check `result.ok`
+- `TrustFlowError` exceptions for configuration and direct network-client failures
 
-Report security issues to: security@trustflow.xyz
+```typescript
+import { TrustFlowClient, TrustFlowError } from '@trustflow/sdk';
+
+try {
+  const client = new TrustFlowClient({
+    contractId: process.env.TRUSTFLOW_CONTRACT_ID!,
+    network: 'TESTNET',
+  });
+  await client.connect();
+} catch (error) {
+  if (error instanceof TrustFlowError) {
+    console.error(error.code, error.message);
+  } else {
+    throw error;
+  }
+}
+```
 
----
+## Project Scripts
 
-## 📜 License
+```bash
+npm install
+npm test
+npm run build
+npm run lint
+```
 
-MIT License - Copyright (c) 2026 TrustFlow Protocol
+## Repository Layout
+
+```text
+src/
+  auth/       Challenge and session helpers
+  contract/   Contract invocation, simulation, and argument builders
+  escrow/     Escrow clients, builders, monitoring, disputes, and multisig
+  stellar/    Network, account, and transaction helpers
+  utils/      Validation, formatting, retry, logging, and cache helpers
+  wallet/     Freighter and Albedo wallet adapters
+examples/     Runnable usage examples
+docs/         Architecture, API, and quickstart notes
+tests/        Jest test suite
+```
 
-See [LICENSE](./LICENSE) for details.
+## Documentation
 
----
+- `docs/QUICKSTART.md`
+- `docs/API.md`
+- `docs/ARCHITECTURE.md`
+- `examples/`
 
-## 🌟 Community
+## Contributing
 
-- **Issues**: [Report bugs or request features](https://github.com/trustflow-protocol/trustflow-sdk/issues)
-- **Contributors**: See [CONTRIBUTORS.md](./CONTRIBUTORS.md)
-- **Changelog**: See [CHANGELOG.md](./CHANGELOG.md)
+1. Fork the repository.
+2. Install dependencies with `npm install`.
+3. Create a topic branch.
+4. Run `npm test`, `npm run build`, and `npm run lint`.
+5. Open a pull request with a short summary and verification notes.
 
----
+## License
 
-*Securing the future of work, one transaction at a time.*
+MIT. See `LICENSE` for details.

From 1157a319f7905ae7f61184949316d9a9d2288acd Mon Sep 17 00:00:00 2001
From: leo1987820 <leo1987820@gmail.com>
Date: Thu, 25 Jun 2026 03:07:00 +0800
Subject: [PATCH 2/2] fix: export TrustFlowClient from package root

---
 src/index.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/index.ts b/src/index.ts
index b703e90..b37d9ae 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -2,6 +2,7 @@ export * from './types';
 export * from './types/contract';
 export * from './types/events';
 export * from './types/multisig';
+export { TrustFlowClient } from './client';
 export * from './escrow';
 export * from './auth';
 export * from './stellar';