skillbase/web3-technical-writing

# @protocol/sdk

TypeScript SDK for interacting with [Protocol] — a cross-chain lending protocol on Arbitrum.

Deposit assets, manage lending positions, and query market data in 5 lines of code.

## Quickstart

```bash

npm install @protocol/sdk viem

```

```typescript

import { createProtocolClient } from '@protocol/sdk';

import { arbitrum } from 'viem/chains';

const client = createProtocolClient({

  chain: arbitrum,

  rpcUrl: 'https://arb1.arbitrum.io/rpc',

});

// Get all available markets

const markets = await client.getMarkets();

console.log(markets);

// [{ asset: 'USDC', totalSupply: '12400000', supplyAPY: '0.0341', ... }, ...]

```

## Prerequisites

- Node.js 18+

- An Arbitrum RPC endpoint ([Alchemy](https://alchemy.com), [Infura](https://infura.io), or public)

- A wallet with assets on Arbitrum (for write operations)

## Installation

```bash

# npm

npm install @protocol/sdk viem

# pnpm

pnpm add @protocol/sdk viem

# yarn

yarn add @protocol/sdk viem

```

`viem` is a peer dependency used for chain configuration and transaction encoding.

## Usage

### Read-only operations (no wallet needed)

```typescript

import { createProtocolClient } from '@protocol/sdk';

import { arbitrum } from 'viem/chains';

const client = createProtocolClient({

  chain: arbitrum,

  rpcUrl: process.env.ARBITRUM_RPC_URL,

});

// Get a specific market

const usdcMarket = await client.getMarket('USDC');

console.log(usdcMarket);

// { asset: 'USDC', totalSupply: '12400000', totalBorrow: '8200000', supplyAPY: '0.0341', borrowAPY: '0.0523' }

// Get a user's positions

const positions = await client.getPositions('0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045');

console.log(positions);

// [{ asset: 'USDC', supplied: '10000', earned: '142.50', healthFactor: '1.82' }]

```

### Write operations (wallet required)

```typescript

import { createProtocolClient } from '@protocol/sdk';

import { createWalletClient, http } from 'viem';

import { arbitrum } from 'viem/chains';

import { privateKeyToAccount } from 'viem/accounts';

const wallet = createWalletClient({

  account: privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`),

  chain: arbitrum,

  transport: http(process.env.ARBITRUM_RPC_URL),

});

const client = createProtocolClient({

  chain: arbitrum,

  rpcUrl: process.env.ARBITRUM_RPC_URL,

  wallet,

});

// Deposit 1000 USDC (requires prior token approval)

const tx = await client.deposit({

  asset: 'USDC',

  amount: '1000000000', // 1000 USDC (6 decimals)

});

console.log(`Deposit tx: https://arbiscan.io/tx/${tx.hash}`);

// Deposit tx: https://arbiscan.io/tx/0xabc...

// Withdraw all supplied USDC

const withdrawTx = await client.withdraw({

  asset: 'USDC',

  amount: 'max',

});

```

> ⚠️ **Warning:** Write operations send on-chain transactions that spend gas. Always test on Arbitrum Sepolia first (chain ID: 421614).

### Token approvals

Before depositing ERC-20 tokens, you must approve the protocol contract:

```typescript

const approvalTx = await client.approve({

  asset: 'USDC',

  amount: '1000000000', // 1000 USDC

});

console.log(`Approval tx: https://arbiscan.io/tx/${approvalTx.hash}`);

// Now deposit

const depositTx = await client.deposit({

  asset: 'USDC',

  amount: '1000000000',

});

```

> 💡 **Note:** Pass `amount: 'unlimited'` to approve once and skip future approval transactions. This is standard practice but means the contract can spend all your USDC — use with protocols you trust.

## Error handling

```typescript

import { ProtocolError, ErrorCode } from '@protocol/sdk';

try {

  await client.deposit({ asset: 'USDC', amount: '1000000000' });

} catch (error) {

  if (error instanceof ProtocolError) {

    switch (error.code) {

      case ErrorCode.INSUFFICIENT_BALANCE:

        // User doesn't have enough USDC

        break;

      case ErrorCode.NOT_APPROVED:

        // Token approval needed — call client.approve() first

        break;

      case ErrorCode.HEALTH_FACTOR_TOO_LOW:

        // This deposit would put an existing borrow position at risk

        break;

    }

  }

}

```

## Contract addresses

| Contract | Arbitrum One (42161) | Arbitrum Sepolia (421614) |

|----------|---------------------|--------------------------|

| LendingPool | `0x...` | `0x...` |

| USDC Market | `0x...` | `0x...` |

| ETH Market | `0x...` | `0x...` |

## API Reference

See [API docs](./docs/api.md) for the complete method reference.

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md).

## License

MIT

## v2.0.0 — 2026-03-14

### ⚠️ Breaking changes

**Migrated from ethers.js to viem.** All wallet-related interfaces have changed.

[Before/after code pair showing ethers.js → viem client initialization]

**`deposit()` now takes a single options object** instead of positional arguments.

[Before/after code pair: `client.deposit('USDC', '1000000000')` → `client.deposit({ asset: 'USDC', amount: '1000000000' })`]

### Migration steps

[4 numbered steps: replace ethers with viem → update initialization → update method calls → run tests. Note that read-only operations are unchanged.]

### Features

- `client.approve({ asset, amount: 'unlimited' })` for one-time approvals

- `amount: 'max'` option in `withdraw()` for full-balance withdrawals

### Fixes

- Fixed gas estimation on Arbitrum One causing ~3% deposit failures. SDK now simulates + 20% gas buffer.

[Structure: Problem (route lending across 5 chains) → Constraints (2min latency, no fund loss, cost scaling, operational complexity) → Two approaches with ASCII diagrams (mesh: n(n-1)/2 connections vs hub-and-spoke: n-1) → Decision table comparing connections/deployment/latency/SPOF/cost → Trade-offs accepted (extra latency mitigated by hub-local liquidity, SPOF mitigated by Arbitrum uptime + graceful degradation) → Alternatives rejected (lazy mesh, multi-hub)]