Trustware SDK Development

This skill helps you work with the Trustware SDK, a React provider, widget, and headless API for cross-chain bridging and top-up routes. It powers seamless fund transfers across chains with typed APIs for quoting, route selection, and transaction execution.

When to Use This Skill

Development Workflow

1. Install Dependencies and Validate Setup

First, ensure all dependencies are installed and the project passes validation:

```bash

npm install

npm run validate

```

The validation runs typechecking, strict linting, and format checks.

2. Start Development Mode

For active development with hot reloading:

```bash

npm run dev

```

This runs the SDK in watch mode, rebuilding automatically on changes.

3. Test with Example Webapp (Local Linking)

To test SDK changes in the example webapp, use npm link:

**Step 1: Create the link from SDK**

```bash

Use nvm to avoid permission issues

nvm use 22

cd /path/to/trustware-sdk

npm link

```

**Step 2: Consume the link in example-webapp**

```bash

cd /path/to/example-webapp

npm link @trustware/sdk

```

**Step 3: Run both in parallel**

Terminal 1 (SDK watch mode):

```bash

cd /path/to/trustware-sdk

npm run dev

```

Terminal 2 (Example webapp):

```bash

cd /path/to/example-webapp

npm run dev

```

**Important**: After running `npm install` in example-webapp, the symlink may be replaced. Re-run `npm link @trustware/sdk` to restore the local link.

4. Build for Production

When ready to build:

```bash

npm run build

```

Output goes to `dist/` with ESM, CJS, and TypeScript declarations.

5. Check Bundle Size

Ensure bundle stays within limits:

```bash

npm run size

```

Limit is 50 KB gzipped.

Architecture Reference

Entry Points

Key Directories

Widget State Machine

The TrustwareWidget follows an 8-state flow:

```

Welcome

→ ChainTokenSelection

→ AmountEntry

→ Quoting

→ WalletConnection

→ PaymentProcessing

→ Success/Failure

```

Each state is defined in `src/widget-v2/`.

WalletConnect Integration

WalletConnect is enabled by default with a built-in project ID. Users can:

Important Implementation Details

Transaction Amount Conversion

**Critical**: Route amounts must be converted to the token's smallest unit (like wei for ETH) before sending to backend.

Location: `src/widget-v2/hooks/useRouteBuilder.ts`

```typescript

const decimals = selectedToken.decimals || 18;

const [whole, fraction = ""] = amount.split(".");

const paddedFraction = fraction.padEnd(decimals, "0").slice(0, decimals);

const fromAmountWei = (whole + paddedFraction).replace(/^0+/, "") || "0";

```

Transaction Receipt Submission

**Critical**: After getting a transaction hash from wallet, you must call `submitReceipt()` to notify the backend.

Location: `src/widget-v2/hooks/useTransactionSubmit.ts`

```typescript

// After sendRouteTransaction() returns hash

await submitReceipt(routeResult.intentId, hash);

```

Design System

Current UI uses:

Files: `src/widget-v2/styles.css`, `tailwind.config.js`

Build Configuration

Code Style

Common Tasks

Adding a New Hook

1. Create hook file in `src/hooks/`

2. Export from `src/hooks/index.ts`

3. Re-export from `src/index.ts` if public API

4. Add TypeScript types in `src/types/`

Modifying Widget State

1. Locate state in `src/widget-v2/`

2. Update state machine logic if changing flow

3. Test all transitions (Welcome → Success/Failure)

4. Verify with example webapp

Updating Wallet Adapters

1. Modify files in `src/wallets/`

2. Test detection logic for all supported wallets

3. Verify WalletConnect flow if applicable

Constraints