npm package: @intentlayer/sdk
Description: TypeScript SDK for building, signing, and verifying intents on Intent Layer
Author: Intent Layer
Latest version: 0.1.5

# @intentlayer/sdk

A TypeScript SDK for building, signing, and verifying intents on Intent Layer.

[![npm version](https://badge.fury.io/js/@intentlayer%2Fsdk.svg)](https://badge.fury.io/js/@intentlayer%2Fsdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Beta Notice

This SDK is in **beta**. Here's what that means for you:

| Area | Stability |
|------|-----------|
| `CloudRuntime` API | Stable — safe to build against |
| Intent signing (`buildIntent`, `signIntent`, `verifyIntent`) | Stable |
| Error types | May expand — new error classes may be added |
| Constraint builders | Stable API, coverage expanding |

Breaking changes will follow semver: breaking = major version bump.

## Features

- **EIP-712 Intent Signing** - Cryptographically secure intent signing with viem
- **Intent Builders** - Easy-to-use functions for building intents
- **Signature Verification** - Verify intent signatures off-chain
- **Type-Safe** - Full TypeScript support with strict types
- **Modern Bundling** - ESM/CJS dual exports for maximum compatibility
- **Minimal Dependencies** - Only depends on viem for maximum efficiency

## Installation

```bash
npm install @intentlayer/sdk viem
# or
yarn add @intentlayer/sdk viem
# or
pnpm add @intentlayer/sdk viem
```

## Quick Start

```typescript
import {
  buildIntent,
  signIntent,
  verifyIntent,
  makeDomain,
} from "@intentlayer/sdk";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";

// Setup wallet
const account = privateKeyToAccount("0x...");
const wallet = createWalletClient({
  account,
  chain: mainnet, // or your target chain
  transport: http(),
});

// Build an intent
const intent = buildIntent({
  policyId: "0x1234...", // Policy ID for the intent
  amount: 100n,
  tokenOrRecip: "0xA0b86a33E6842740073e8138aA1204a5d9e31e85", // Token address
  nonce: 0,
  intentType: 0,
  sigType: 0,
  callData: "0x...", // ABI-encoded function call
  validFor: 3600, // Valid for 1 hour
});

// Sign the intent
const domain = makeDomain(1, "0x..."); // chainId, Intent Manager address
const signedIntent = await signIntent(intent, domain, wallet);

// Verify the signature
const isValid = await verifyIntent(signedIntent, domain, account.address);

console.log("Intent signed and verified:", isValid);
```

## Core Concepts

### Intent Structure

An intent represents a user's desire to perform an action:

```typescript
interface Intent {
  policyId: HexString; // Policy governing this intent
  amount: bigint; // Amount in smallest units
  tokenOrRecip: Address; // Token or recipient address
  validUntil: number; // Unix timestamp when intent expires
  nonce: number; // Anti-replay nonce
  intentType: number; // Intent type discriminator
  sigType: number; // Signature type (0 = EOA/EIP-712)
  callData: HexString; // Executor call data
  signature?: HexString; // EIP-712 signature (added by signIntent)
}
```

### EIP-712 Domain

The SDK uses EIP-712 for secure intent signing:

```typescript
const domain = makeDomain(
  31337, // Chain ID (Hardhat local)
  "0x9fE46736679d2D9a65F0992F2272dE9f3c7fa6e0" // Intent Manager contract address
);
```

## API Reference

### Core Functions

#### `buildIntent(args: BuildIntentArgs): Intent`

Creates an unsigned intent object.

```typescript
const intent = buildIntent({
  policyId: "0x...",
  amount: 100n,
  tokenOrRecip: "0x...",
  nonce: 0,
  intentType: 0,
  sigType: 0,
  callData: "0x...",
  validFor: 3600, // Seconds until expiry
});
```

#### `signIntent(intent, domain, wallet): Promise<Intent>`

Signs an intent using EIP-712.

```typescript
const signedIntent = await signIntent(intent, domain, walletClient);
```

#### `verifyIntent(intent, domain, signer): Promise<boolean>`

Verifies an intent signature.

```typescript
const isValid = await verifyIntent(signedIntent, domain, signerAddress);
```

#### `getDigest(intent, domain): HexString`

Computes the EIP-712 digest for an intent.

```typescript
const digest = getDigest(intent, domain);
```

#### `makeDomain(chainId, verifyingContract): TypedDataDomain`

Creates the EIP-712 domain for intent signing.

```typescript
const domain = makeDomain(1, intentManagerAddress);
```

### Executor Helpers

#### `buildPermit2ExecutorCalldata(args): HexString`

Builds calldata for ERC20 token transfers via Permit2Executor.

```typescript
import { buildPermit2ExecutorCalldata } from "@intentlayer/sdk";

const callData = buildPermit2ExecutorCalldata({
  owner: "0x...", // Token owner address
  token: "0x...", // Token contract address
  to: "0x...", // Recipient address
  amount: 100n, // Amount in token's smallest unit
});
```

## Testing

The SDK includes comprehensive tests:

```bash
# Run tests
yarn test

# Run tests in watch mode
yarn test:watch

# Run specific test
yarn test intent.test.ts
```

## Build from Source

```bash
# Install dependencies
yarn install

# Build the SDK
yarn build

# Run tests
yarn test

# Generate documentation
yarn docs
```

## Examples

### Token Transfer Intent

```typescript
import { buildIntent, buildPermit2ExecutorCalldata } from "@intentlayer/sdk";

// Build executor calldata for token transfer
const callData = buildPermit2ExecutorCalldata({
  owner: wallet.account.address,
  token: "0xA0b86a33E6842740073e8138aA1204a5d9e31e85",
  to: "0x742d35Cc641C0532F23c7C4de5Ff2ff2B2Acf5A2",
  amount: parseUnits("100", 18), // 100 tokens
});

// Build the intent
const intent = buildIntent({
  policyId: "0x1234...",
  amount: parseUnits("100", 18),
  tokenOrRecip: "0xA0b86a33E6842740073e8138aA1204a5d9e31e85",
  nonce: 0,
  intentType: 0,
  sigType: 0,
  callData,
  validFor: 3600, // 1 hour
});
```

### Batch Operations

```typescript
// Multiple intents can be created and signed together
const intents = await Promise.all([
  signIntent(intent1, domain, wallet),
  signIntent(intent2, domain, wallet),
  signIntent(intent3, domain, wallet),
]);
```

## Development

This SDK is part of the Intent Layer monorepo. See the main README for development setup.

## License

MIT License - see LICENSE file for details.