dbis-thirdweb/README.md

# dbis-thirdweb

Chain 138 full enablement for thirdweb offerings: **Wallets**, **x402**, **Bridge**, **Tokens**, **AI**, and **HTTP API**.

## Overview

This monorepo provides complete enablement of Chain 138 (ChainID 138) across six core thirdweb offerings. Each offering is implemented as an independent package with its own API, tests, and documentation.

## Structure

```
packages/
  chain/      - Chain 138 canonical definition (CAIP-2: eip155:138)
  wallets/    - Wallet connectors & configuration
  x402/       - Payment primitives & pay-to-access flows
  bridge/     - Bridge routes & execution helpers
  tokens/     - ERC20/721/1155 deployment & management
  ai/         - Chain-aware AI prompts & actions
  http-api/   - HTTP API client wrapper with retries

apps/
  smoke-tests/ - End-to-end tests for all 6 offerings
```

## Prerequisites

- Node.js >= 18.0.0
- pnpm >= 8.0.0
- Access to Chain 138 RPC endpoint (default: https://138.rpc.thirdweb.com)

## Setup

1. Install dependencies:
```bash
pnpm install
```

2. Build all packages:
```bash
pnpm build
```

3. Run smoke tests (optional - requires test private key):
```bash
cd apps/smoke-tests
cp .env.example .env
# Edit .env with your TEST_PRIVATE_KEY
pnpm test
```

## Usage

Each package can be imported independently:

```typescript
import { chain138 } from '@dbis-thirdweb/chain';
import { getWalletConfig, switchToChain138 } from '@dbis-thirdweb/wallets';
import { PayToAccessFlow } from '@dbis-thirdweb/x402';
import { generateBridgeQuote } from '@dbis-thirdweb/bridge';
import { createTokenFactory } from '@dbis-thirdweb/tokens';
import { createReadPrompt } from '@dbis-thirdweb/ai';
import { createChain138API } from '@dbis-thirdweb/http-api';
```

See individual package READMEs for detailed usage:
- [`packages/chain/README.md`](packages/chain/README.md)
- [`packages/wallets/README.md`](packages/wallets/README.md)
- [`packages/x402/README.md`](packages/x402/README.md)
- [`packages/bridge/README.md`](packages/bridge/README.md)
- [`packages/tokens/README.md`](packages/tokens/README.md)
- [`packages/ai/README.md`](packages/ai/README.md)
- [`packages/http-api/README.md`](packages/http-api/README.md)

## Development

### Build

Build all packages:
```bash
pnpm build
```

Build specific package:
```bash
pnpm --filter @dbis-thirdweb/chain build
```

### Testing

Run all smoke tests:
```bash
pnpm smoke-tests
```

Run specific test suite:
```bash
cd apps/smoke-tests
pnpm test:wallets
pnpm test:x402
pnpm test:bridge
pnpm test:tokens
pnpm test:ai
pnpm test:http-api
```

### Linting

Lint all packages:
```bash
pnpm lint
```

## Package Details

### @dbis-thirdweb/chain
Canonical Chain 138 definition with chain ID, RPC endpoints, native currency, and explorer configuration.

### @dbis-thirdweb/wallets
Wallet configuration defaults, chain switching utilities, and RPC failover for Chain 138.

### @dbis-thirdweb/x402
Payment primitives, pay-to-access flows, replay protection, and receipt verification for Chain 138.

### @dbis-thirdweb/bridge
Bridge route configuration, token lists, quote generation, and execution helpers for bridging to Chain 138.

### @dbis-thirdweb/tokens
ERC20/721/1155 token deployment, minting, transfers, and metadata hosting for Chain 138.

### @dbis-thirdweb/ai
Chain-aware AI prompt templates, read/write action templates, and chain ID validation for Chain 138.

### @dbis-thirdweb/http-api
HTTP API client wrapper with retry logic, exponential backoff, timeouts, and Chain 138-specific endpoints.

## Troubleshooting

### Common Issues

1. **Build errors**: Ensure all dependencies are installed with `pnpm install`
2. **Test failures**: Check that `TEST_PRIVATE_KEY` is set in `apps/smoke-tests/.env`
3. **RPC connection errors**: Verify Chain 138 RPC endpoint is accessible
4. **Chain mismatch errors**: Ensure you're using Chain 138 (chainId: 138) in your configuration

### Getting Help

- Check individual package READMEs for package-specific issues
- Review smoke test output for detailed error messages
- Verify Chain 138 is properly configured in thirdweb dashboard

## License

MIT