@defuse-protocol/intents-sdk 0.14.0

package/README.md

@@ -0,0 +1,732 @@
+# @defuse-protocol/intents-sdk
+
+The Intents SDK for Near Intents provides a set of tools for interacting with various bridge implementations. It simplifies the process of transferring assets from Near Intents to different blockchains.
+
+## Features
+
+- Bridging from Near Intents:
+  - Support for multiple bridge implementations (Hot, PoA)
+  - Single and batch withdrawal operations
+  - Automatic fee estimation
+  - Built-in validation for withdrawal constraints:
+    - PoA Bridge minimum withdrawal amounts
+    - Hot Bridge Stellar trustline validation
+  - Transfers within Near Intents
+  - Transfers to NEAR blockchain
+  - Transfers to Virtual Chains (e.g. Aurora)
+
+
+
+Note: Bridging to Near Intents is not supported yet.
+  
+## Installation
+
+```bash
+npm install @defuse-protocol/intents-sdk --save-exact
+```
+
+## Quick Start
+
+```typescript
+import { IntentsSDK, createIntentSignerNearKeyPair } from '@defuse-protocol/intents-sdk';
+import { KeyPair } from 'near-api-js';
+
+// Initialize the SDK with required configuration
+const sdk = new IntentsSDK({
+    referral: 'your-referral-code', // Only referral is required
+});
+
+// Set up intent signer (for NEAR)
+const keypair = KeyPair.fromString('your-private-key');
+const signer = createIntentSignerNearKeyPair({
+  keypair: keypair,
+  accountId: 'your-account.near'
+});
+sdk.setIntentSigner(signer);
+
+// Method 1: Complete end-to-end withdrawal (orchestrated)
+const result = await sdk.processWithdrawal({
+  withdrawalParams: {
+    assetId: 'nep141:usdt.tether-token.near', // Asset identifier
+    amount: 1000000n, // Amount in smallest unit
+    destinationAddress: '0x742d35Cc6634C0532925a3b8D84B2021F90a51A3',
+    feeInclusive: false, // Whether amount includes fees
+    // routeConfig is optional - will be auto-detected from assetId
+  }
+});
+
+console.log('Intent hash:', result.intentHash);
+console.log('Destination tx:', result.destinationTx);
+
+// Method 2: Granular control with individual methods
+const feeEstimation = await sdk.estimateWithdrawalFee({
+  withdrawalParams: {
+    assetId: 'nep141:usdt.tether-token.near',
+    amount: 1000000n,
+    destinationAddress: '0x742d35Cc6634C0532925a3b8D84B2021F90a51A3',
+    feeInclusive: false
+  }
+});
+
+const { intentHash } = await sdk.signAndSendWithdrawalIntent({
+  withdrawalParams: {
+    assetId: 'nep141:usdt.tether-token.near',
+    amount: 1000000n,
+    destinationAddress: '0x742d35Cc6634C0532925a3b8D84B2021F90a51A3',
+    feeInclusive: false
+  },
+  feeEstimation
+});
+
+const intentTx = await sdk.waitForIntentSettlement({ intentHash });
+const destinationTx = await sdk.waitForWithdrawalCompletion({ 
+  withdrawalParams: {
+    assetId: 'nep141:usdt.tether-token.near',
+    amount: 1000000n,
+    destinationAddress: '0x742d35Cc6634C0532925a3b8D84B2021F90a51A3',
+    feeInclusive: false
+  }, 
+  intentTx 
+});
+```
+
+## Core Concepts
+
+### Route and Bridge Enums
+
+The SDK uses two key concepts to organize withdrawal operations:
+
+#### Routes
+Routes define the **path** a withdrawal takes - the specific mechanism and destination for transferring assets. Each route represents a different withdrawal flow:
+
+```typescript
+import { RouteEnum } from '@defuse-protocol/intents-sdk';
+
+console.log(RouteEnum.HotBridge);        // "hot_bridge" - Cross-chain via HOT protocol
+console.log(RouteEnum.PoaBridge);        // "poa_bridge" - Cross-chain via PoA bridge
+console.log(RouteEnum.NearWithdrawal);   // "near_withdrawal" - Direct to NEAR blockchain
+console.log(RouteEnum.VirtualChain);     // "virtual_chain" - To Aurora Engine chains
+console.log(RouteEnum.InternalTransfer); // "internal_transfer" - Between protocol users
+```
+
+#### Bridge Names
+Bridge names identify the **underlying bridge infrastructure** that handles the cross-chain transfer. This determines which external protocol processes the withdrawal:
+
+```typescript
+import { BridgeNameEnum } from '@defuse-protocol/intents-sdk';
+
+console.log(BridgeNameEnum.Hot);  // "hot" - HOT Labs bridge infrastructure
+console.log(BridgeNameEnum.Poa);  // "poa" - Proof-of-Authority bridge by Defuse Labs  
+console.log(BridgeNameEnum.None); // null - No external bridge (NEAR-native or internal)
+```
+
+**Key Difference**: 
+- **Route** = "How and where" the withdrawal goes (the path)
+- **Bridge Name** = "Who operates" the underlying infrastructure (the bridge provider)
+
+For example, both `hot_bridge` and `poa_bridge` routes perform cross-chain transfers, but use different bridge infrastructures (`hot` vs `poa`) with different fee structures and supported networks.
+
+### Asset Identifiers
+
+The SDK uses standardized asset identifiers in the format:
+- `nep141:contract.near` - NEP-141 tokens
+- `nep245:contract.near:tokenId` - NEP-245 multi-tokens
+
+Asset Identifier uniquely determines the corresponding route and destination chain.
+
+Examples:
+- `nep141:usdt.tether-token.near` - USDT on NEAR
+- `nep141:wrap.near` - Wrapped NEAR (native NEAR)
+- `nep245:v2_1.omni.hot.tg:137_qiStmoQJDQPTebaPjgx5VBxZv6L` - Polygon USDC through Hot
+- `nep141:base-0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.omft.near` - Base USDC through PoA
+
+### Intent Signers
+
+Intent signers are required to authenticate and sign withdrawal operations. The SDK supports multiple signing methods:
+
+- **NEAR KeyPair Signer** - Use NEAR account private keys for signing
+- **NEP-413 Signer** - Custom message signing implementation 
+- **EVM/Viem Signer** - Use Ethereum-compatible wallets and accounts
+
+You must set an intent signer before processing withdrawals:
+
+```typescript
+// Example: Set up a NEAR KeyPair signer
+const signer = createIntentSignerNearKeyPair({
+  keypair: KeyPair.fromString('your-private-key'),
+  accountId: 'your-account.near'
+});
+sdk.setIntentSigner(signer);
+```
+
+See the [Intent Signers](#intent-signers-1) section below for detailed implementation examples.
+
+## Route Types
+
+The SDK automatically detects and supports multiple route types based on asset identifiers:
+
+### Hot Bridge Route
+- **Purpose**: Cross-chain transfers via HOT Labs infrastructure
+- **Supported Assets**: Multi-tokens (NEP-245) from Hot protocol (contract `v2_1.omni.hot.tg`)
+- **Use Case**: Cross-chain transfers for assets bridged through Hot protocol
+- **Route Type**: `hot_bridge`
+
+### PoA Bridge Route  
+- **Purpose**: Proof-of-Authority bridge transfers operated by Defuse Labs
+- **Supported Assets**: Fungible tokens (NEP-141) ending with `.omft.near`
+- **Use Case**: Cross-chain transfers for assets bridged through PoA protocol
+- **Route Type**: `poa_bridge`
+
+### Internal Transfer Route
+- **Purpose**: Transfer between Near Intents users within the protocol
+- **Supported Assets**: All NEP-141 and NEP-245 tokens
+- **Use Case**: User A having funds in the protocol wants to transfer to User B
+- **Route Type**: `internal_transfer`
+
+### Near Withdrawal Route
+- **Purpose**: Transfers within the NEAR blockchain
+- **Supported Assets**: NEP-141 tokens on NEAR, including native NEAR (wrap.near)
+- **Use Case**: Same-chain transfers on NEAR
+- **Route Type**: `near_withdrawal`
+
+### Virtual Chain Route
+- **Purpose**: Transfers to Aurora Engine-powered chains (aka Virtual chains)
+- **Supported Assets**: NEP-141 tokens with Aurora Engine integration
+- **Use Case**: Near Intents to Aurora ecosystem transfers
+- **Route Type**: `virtual_chain`
+- **Note**: Requires explicit `routeConfig` with `auroraEngineContractId`
+
+### Fee Estimation
+
+The SDK now supports both single and batch fee estimation:
+
+```typescript
+// Single withdrawal fee estimation
+const feeEstimation = await sdk.estimateWithdrawalFee({
+  withdrawalParams: {
+    assetId: 'nep141:usdt.tether-token.near',
+    amount: 1000000n,
+    destinationAddress: '0x742d35Cc6634C0532925a3b8D84B2021F90a51A3',
+    feeInclusive: false
+  }
+});
+
+console.log('Fee amount:', feeEstimation.amount);
+console.log('Quote info:', feeEstimation.quote); // null if fee paid with withdrawn token
+
+// Batch fee estimation
+const batchFees = await sdk.estimateWithdrawalFee({
+  withdrawalParams: [
+    {
+      assetId: 'nep141:usdt.tether-token.near',
+      amount: 1000000n,
+      destinationAddress: '0x742d35Cc...',
+      feeInclusive: false
+    },
+    {
+      assetId: 'nep245:v2_1.omni.hot.tg:137_qiStmoQJDQPTebaPjgx5VBxZv6L',
+      amount: 500000n,
+      destinationAddress: '0x742d35Cc...',
+      feeInclusive: false
+    }
+  ]
+});
+
+console.log('Batch fees:', batchFees); // Array of FeeEstimation objects
+```
+
+### Intent Signers
+
+The SDK supports multiple intent signing methods using factory functions:
+
+#### NEAR KeyPair Signer
+```typescript
+import { createIntentSignerNearKeyPair, IntentsSDK } from '@defuse-protocol/intents-sdk';
+import { KeyPair } from 'near-api-js';
+
+const keyPair = KeyPair.fromString('your-private-key');
+const signer = createIntentSignerNearKeyPair({
+  keypair: keyPair,
+  accountId: 'your-account.near'
+});
+```
+
+#### NEP-413 Signer
+```typescript
+import { createIntentSignerNEP413 } from '@defuse-protocol/intents-sdk';
+
+const signer = createIntentSignerNEP413({
+  signMessage: async (nep413Payload, nep413Hash) => {
+    // Implement your custom signing logic here
+    return {
+      publicKey: 'ed25519:YourPublicKey',
+      signature: 'base64-encoded-signature'
+    };
+  },
+  accountId: 'your-account.near'
+});
+```
+
+#### EVM/Viem Signer
+```typescript
+import { createIntentSignerViem } from '@defuse-protocol/intents-sdk';
+import { privateKeyToAccount } from 'viem/accounts';
+
+const account = privateKeyToAccount('0x...');
+const signer = createIntentSignerViem(account);
+
+// Set the signer at runtime
+sdk.setIntentSigner(signer);
+```
+
+## Advanced Usage
+
+### Custom RPC URLs
+
+Set NEAR and EVM chains RPC URLs in the constructor: 
+
+```typescript
+import { Chains } from '@defuse-protocol/intents-sdk'
+
+const sdk = new IntentsSDK({
+    ...,
+    rpc: {
+        [Chains.Near]: ['https://rpc.mainnet.near.org'],
+        [Chains.Polygon]: ['https://polygon-rpc.com'],
+        [Chains.BNB]: ['https://bsc-dataseed.binance.org'],
+    }
+});
+```
+
+### Intent Publishing Hooks
+
+Use the `onBeforePublishIntent` hook to intercept and process intent data before it's published to the relayer. This is useful for persistence, logging, analytics, or custom processing:
+
+```typescript
+import { type OnBeforePublishIntentHook } from '@defuse-protocol/intents-sdk';
+
+// Define your hook function
+const onBeforePublishIntent: OnBeforePublishIntentHook = async (intentData) => {
+  // Save to database for tracking
+  await saveIntentToDatabase({
+    hash: intentData.intentHash,
+    payload: intentData.intentPayload,
+    timestamp: new Date(),
+  });
+  
+  // Send analytics
+  analytics.track('intent_about_to_publish', {
+    intentHash: intentData.intentHash,
+    intentType: intentData.intentPayload.intents[0]?.intent,
+  });
+};
+
+// Use the hook with the functional API
+const result = await sdk.processWithdrawal({
+  withdrawalParams: { /* ... */ },
+  intent: {
+    onBeforePublishIntent, // Add the hook here
+  }
+});
+
+// Or with granular control
+const { intentHash } = await sdk.signAndSendWithdrawalIntent({
+  withdrawalParams: { /* ... */ },
+  feeEstimation: fee,
+  intent: {
+    onBeforePublishIntent, // Add the hook here
+  }
+});
+
+// Or with generic intent publishing
+const { intentHash } = await sdk.signAndSendIntent({
+  intents: [/* ... */],
+  onBeforePublishIntent, // Add the hook here
+});
+```
+
+**Hook Parameters:**
+- `intentHash` - The computed hash of the intent payload
+- `intentPayload` - The unsigned intent payload
+- `multiPayload` - The signed multi-payload containing signature and metadata
+- `relayParams` - Additional parameters passed to the relayer (quote hashes)
+
+**Important Notes:**
+- The hook is called synchronously before publishing the intent
+- If the hook throws an error, the withdrawal will fail
+- The hook can be async and return a Promise
+
+### Batch Withdrawals
+
+Process multiple withdrawals in a single intent:
+
+```typescript
+const withdrawalParams = [
+  {
+    assetId: 'nep141:usdt.tether-token.near',
+    amount: 1000000n,
+    destinationAddress: '0x742d35Cc...',
+    feeInclusive: false
+  },
+  {
+    assetId: 'nep245:v2_1.omni.hot.tg:137_qiStmoQJDQPTebaPjgx5VBxZv6L',
+    amount: 100000n,
+    destinationAddress: '0x742d35Cc...',
+    feeInclusive: false
+  }
+]
+
+// Method 1: Complete end-to-end batch processing
+const batchResult = await sdk.processWithdrawal({
+  withdrawalParams,
+  // feeEstimation is optional - will be estimated automatically if not provided
+});
+
+console.log('Batch intent hash:', batchResult.intentHash);
+console.log('Destination transactions:', batchResult.destinationTx); // Array of results
+
+// Method 2: Step-by-step batch processing for granular control
+const feeEstimation = await sdk.estimateWithdrawalFee({
+  withdrawalParams
+});
+
+const { intentHash } = await sdk.signAndSendWithdrawalIntent({
+  withdrawalParams,
+  feeEstimation
+});
+
+const intentTx = await sdk.waitForIntentSettlement({ intentHash });
+
+const destinationTxs = await sdk.waitForWithdrawalCompletion({
+  withdrawalParams,
+  intentTx
+});
+
+console.log('All destination transactions:', destinationTxs);
+```
+
+### Intent Management
+
+The SDK provides direct access to intent operations for advanced use cases:
+
+```typescript
+// Generic intent signing and publishing
+const { intentHash } = await sdk.signAndSendIntent({
+  intents: [/* array of intent primitives */],
+  signer: customIntentSigner, // optional - uses SDK default if not provided
+  onBeforePublishIntent: async (data) => {
+    // Custom logic before publishing
+    console.log('About to publish intent:', data.intentHash);
+  }
+});
+
+// Wait for intent settlement
+const intentTx = await sdk.waitForIntentSettlement({ 
+  intentHash 
+});
+
+// or manual status check
+
+// Check intent status at any time
+const status = await sdk.getIntentStatus({ 
+  intentHash: intentHash 
+});
+
+console.log('Intent status:', status.status); // "PENDING" | "TX_BROADCASTED" | "SETTLED" | "NOT_FOUND_OR_NOT_VALID"
+
+if (status.status === 'SETTLED') {
+  console.log('Settlement transaction:', status.txHash);
+}
+```
+
+**Intent Status Values:**
+- `PENDING` - Intent published but not yet processed
+- `TX_BROADCASTED` - Intent being processed, transaction broadcasted
+- `SETTLED` - Intent successfully completed
+- `NOT_FOUND_OR_NOT_VALID` - Intent not found or invalid, it isn't executed onchain
+
+### Route Configuration Factory Functions
+
+**Recommended**: Use factory functions to create route configurations. The SDK provides factory functions for type-safe and convenient route configuration creation:
+
+```typescript
+import { 
+  createVirtualChainRoute, 
+  createNearWithdrawalRoute, 
+  createInternalTransferRoute 
+} from '@defuse-protocol/intents-sdk';
+
+// Create virtual chain route configuration (recommended)
+const virtualChainRoute = createVirtualChainRoute(
+  '0x4e45415f.c.aurora', // Aurora Engine contract ID
+  null // Proxy token contract ID (optional)
+);
+
+// Create near withdrawal route with custom message
+const nearWithdrawalRoute = createNearWithdrawalRoute(
+  'Custom withdrawal message' // Optional message
+);
+
+// Create internal transfer route
+const internalTransferRoute = createInternalTransferRoute();
+
+// Use the factory-created route configuration in withdrawal
+const result = await sdk.processWithdrawal({
+  withdrawalParams: {
+    assetId: 'nep141:a35923162c49cf95e6bf26623385eb431ad920d3.factory.bridge.near',
+    amount: BigInt('1000000'),
+    destinationAddress: '0x742d35Cc6634C0532925a3b8D84B2021F90a51A3',
+    feeInclusive: false,
+    routeConfig: virtualChainRoute // Recommended: Use factory function
+  }
+});
+```
+
+### Asset Information Parsing
+
+Get detailed information about supported assets:
+
+```typescript
+try {
+  const assetInfo = sdk.parseAssetId('nep141:usdt.tether-token.near');
+  console.log('Bridge name:', assetInfo.bridgeName);
+  console.log('Blockchain:', assetInfo.blockchain);
+  console.log('Contract ID:', assetInfo.contractId);
+  console.log('Standard:', assetInfo.standard);
+} catch (error) {
+  console.log('Asset not supported');
+}
+```
+
+### Waiting for Completion
+
+Monitor withdrawal completion:
+
+```typescript
+// Method 1: Using the orchestrated approach (automatic monitoring)
+const result = await sdk.processWithdrawal({
+  withdrawalParams: {
+    assetId: 'nep141:usdt.tether-token.near',
+    amount: 1000000n,
+    destinationAddress: '0x742d35Cc...',
+    feeInclusive: false
+  }
+});
+
+console.log('Intent settled:', result.intentTx.hash);
+console.log('Withdrawal completed:', result.destinationTx);
+
+// Method 2: Step-by-step monitoring for granular control
+const feeEstimation = await sdk.estimateWithdrawalFee({
+  withdrawalParams: {
+    assetId: 'nep141:usdt.tether-token.near',
+    amount: 1000000n,
+    destinationAddress: '0x742d35Cc...',
+    feeInclusive: false
+  }
+});
+
+const { intentHash } = await sdk.signAndSendWithdrawalIntent({
+  withdrawalParams: {
+    assetId: 'nep141:usdt.tether-token.near',
+    amount: 1000000n,
+    destinationAddress: '0x742d35Cc...',
+    feeInclusive: false
+  },
+  feeEstimation
+});
+
+// Monitor intent settlement
+const intentTx = await sdk.waitForIntentSettlement({ intentHash });
+console.log('Intent settled:', intentTx.hash);
+
+// Wait for withdrawal completion on destination chain
+const completionResult = await sdk.waitForWithdrawalCompletion({
+  withdrawalParams: {
+    assetId: 'nep141:usdt.tether-token.near',
+    amount: 1000000n,
+    destinationAddress: '0x742d35Cc...',
+    feeInclusive: false
+  },
+  intentTx
+});
+
+if ('hash' in completionResult) {
+  console.log('Withdrawal completed with hash:', completionResult.hash);
+} else {
+  console.log('Withdrawal completion not trackable for this bridge');
+}
+```
+
+### Error Handling
+
+```typescript
+import { FeeExceedsAmountError, MinWithdrawalAmountError } from '@defuse-protocol/intents-sdk';
+
+try {
+  const result = await sdk.processWithdrawal({
+    withdrawalParams: {
+      assetId: 'nep141:usdt.tether-token.near',
+      amount: BigInt('100'), // Very small amount
+      destinationAddress: '0x742d35Cc...',
+      feeInclusive: true // Fee must be less than amount
+    }
+  });
+} catch (error) {
+  if (error instanceof FeeExceedsAmountError) {
+    console.log('Fee exceeds withdrawal amount');
+    console.log('Required fee:', error.feeEstimation.amount);
+    console.log('Withdrawal amount:', error.amount);
+  } else if (error instanceof MinWithdrawalAmountError) {
+    console.log('Amount below minimum withdrawal limit');
+    console.log('Minimum required:', error.minAmount);
+    console.log('Requested amount:', error.requestedAmount);
+    console.log('Asset:', error.assetId);
+  }
+}
+
+// Error handling with granular control
+try {
+  const feeEstimation = await sdk.estimateWithdrawalFee({
+    withdrawalParams: {
+      assetId: 'nep141:usdt.tether-token.near',
+      amount: 100n,
+      destinationAddress: '0x742d35Cc...',
+      feeInclusive: true
+    }
+  });
+  
+  // Continue with other operations...
+} catch (error) {
+  // Handle specific errors at each step
+  console.error('Fee estimation failed:', error);
+}
+```
+
+#### PoA Bridge Minimum Withdrawal Amount Validation
+
+PoA bridge has minimum withdrawal amount requirements that vary per token and blockchain. The SDK automatically validates this for all withdrawals.
+
+```typescript
+// Validation happens automatically during withdrawal processing:
+try {
+  const result = await sdk.processWithdrawal({
+    withdrawalParams: {
+      assetId: 'nep141:zec.omft.near', // Zcash token
+      amount: BigInt('50000000'), // 0.5 ZEC (in smallest units)
+      destinationAddress: 'your-zcash-address',
+      feeInclusive: false
+    }
+  });
+} catch (error) {
+  if (error instanceof MinWithdrawalAmountError) {
+    console.log(`Minimum withdrawal for ${error.assetId}: ${error.minAmount}`);
+    console.log(`Requested amount: ${error.requestedAmount}`);
+    // For Zcash: minimum is typically 1.0 ZEC (100000000 in smallest units)
+    // Plus 0.2 ZEC fee, so user needs at least 1.2 ZEC to withdraw 1.0 ZEC
+  }
+}
+```
+
+Note: Other routes (Near Withdrawal, Virtual Chain, Internal Transfer) don't have minimum withdrawal restrictions, so validation passes through for those routes.
+
+#### Hot Bridge Stellar Trustline Validation
+
+Hot Bridge validates that destination addresses have the required trustlines when withdrawing to Stellar blockchain. This prevents failed transactions due to missing trustlines.
+
+```typescript
+import { TrustlineNotFoundError } from '@defuse-protocol/intents-sdk';
+
+// Validation happens automatically during withdrawal processing:
+try {
+  const result = await sdk.processWithdrawal({
+    withdrawalParams: {
+      assetId: 'nep245:v2_1.omni.hot.tg:stellar_1_USD_GBDMM6LG7YX7YGF6JFAEWX3KFUSBXGAEPZ2IHDLWH:1100', // Stellar USD token
+      amount: BigInt('1000000'), // 1 USD (in smallest units)
+      destinationAddress: 'GCKFBEIYTKP6RYVDYGMVVMJ6J6XKCRZL74JPWTFGD2NQNMPBQC2LGTVZ', // Stellar address
+      feeInclusive: false
+    }
+  });
+} catch (error) {
+  if (error instanceof TrustlineNotFoundError) {
+    console.log(`Trustline not found for token: ${error.assetId}`);
+    console.log(`Destination address: ${error.destinationAddress}`);
+    console.log('The destination address must have a trustline for this token before withdrawal');
+    // User needs to create a trustline for the token on Stellar before withdrawing
+  }
+}
+```
+
+**What is a trustline?**
+On Stellar, accounts must explicitly create "trustlines" to hold non-native assets. Before receiving any token (except XLM), the destination address must:
+1. Create a trustline for that specific token
+2. Have sufficient XLM balance to maintain the trustline
+
+**Why this validation matters:**
+- Prevents failed withdrawals due to missing trustlines
+- Saves gas fees and reduces user frustration
+- Provides clear error messages for troubleshooting
+
+Note: This validation only applies to Stellar destinations via Hot Bridge. Other blockchains and routes don't require trustline validation.
+
+TBD
+
+## Supported Networks
+
+For a list of supported chains, see the [Chain Support page](https://docs.near-intents.org/near-intents/chain-address-support) in the Near Intents documentation.
+
+## Development
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org/) (v20 or later)
+- [pnpm](https://pnpm.io/) for package management
+
+### Setup
+
+```bash
+# Install dependencies (from the monorepo root)
+pnpm install
+```
+
+### Build
+
+```bash
+# Build the package
+pnpm run build
+
+# Build in watch mode
+pnpm run dev
+```
+
+### Test
+
+```bash
+# Run tests
+pnpm run test
+
+# Run tests in watch mode  
+pnpm run test:watch
+```
+
+### Lint and Format
+
+```bash
+# Check code style
+pnpm run lint
+
+# Format code
+pnpm run format
+```
+
+## Version History
+
+See [CHANGELOG.md](./CHANGELOG.md) for detailed version history and migration guides.
+
+## Contributing
+
+This package is part of Near Intents SDK monorepo. Please refer to the main repository's contributing guidelines.
+
+## License
+
+MIT