iel-sdk

A TypeScript SDK for building, signing, and verifying intents on the Intent Execution Layer (IEL).

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

npm install @costruct/iel-sdk viem
# or
yarn add @costruct/iel-sdk viem
# or
pnpm add @costruct/iel-sdk viem

Quick Start

import {
  buildIntent,
  signIntent,
  verifyIntent,
  makeDomain,
} from "@costruct/iel-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:

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:

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.

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.

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

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

Verifies an intent signature.

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

getDigest(intent, domain): HexString

Computes the EIP-712 digest for an intent.

const digest = getDigest(intent, domain);

makeDomain(chainId, verifyingContract): TypedDataDomain

Creates the EIP-712 domain for intent signing.

const domain = makeDomain(1, intentManagerAddress);

Executor Helpers

buildPermit2Calldata(args): HexString

Builds calldata for ERC20 token transfers via ExecutorERC20.

import { buildPermit2Calldata } from "@costruct/iel-sdk";

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

Testing

The SDK includes comprehensive tests:

# Run tests
yarn test

# Run tests in watch mode
yarn test:watch

# Run specific test
yarn test intent.test.ts

Build from Source

# Install dependencies
yarn install

# Build the SDK
yarn build

# Run tests
yarn test

# Generate documentation
yarn docs

Examples

Token Transfer Intent

import { buildIntent, buildPermit2Calldata } from "@costruct/iel-sdk";

// Build executor calldata for token transfer
const callData = buildPermit2Calldata({
  token: "0xA0b86a33E6842740073e8138aA1204a5d9e31e85",
  from: wallet.account.address,
  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

// 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 IEL monorepo. See the main README for development setup.

License

MIT License - see LICENSE file for details.