Relay Settlement SDK

TypeScript SDK for encoding/decoding and passing messages accross the Relay Settlement Protocol.

Installation

npm install @relay-protocol/settlement-sdk
# or
yarn add @relay-protocol/settlement-sdk

Usage

Orders

import {
  encodeOrderCall,
  decodeOrderCall,
  getOrderId,
} from "@relay-protocol/settlement-sdk"

// Encode an order call
const encoded = encodeOrderCall({
  vmType: "ethereum-vm",
  call: {
    to: "0x...",
    data: "0x...",
    value: "1000000000000000000",
  },
})

// Decode an order call
const decoded = decodeOrderCall(encoded, "ethereum-vm")

// Get order ID
const orderId = getOrderId(order, chainsConfig)

Address Encoding

import {
  encodeAddress,
  decodeAddress,
  VmType,
} from "@relay-protocol/settlement-sdk"

// Encode address for a specific VM type
const encoded = encodeAddress("bc1q...", "bitcoin-vm")
const decoded = decodeAddress(encoded, "bitcoin-vm")

Hub Contract utils

import {
  generateAddress,
  generateTokenId,
} from "@relay-protocol/settlement-sdk"

// Generate virtual address
const virtualAddress = generateAddress({
  family: "ethereum-vm",
  chainId: 1n,
  address: "0x...",
})

// Generate token ID
const tokenId = generateTokenId({
  family: "ethereum-vm",
  chainId: 1n,
  address: "0x...",
})

Depository Contracts utils

import {
  encodeWithdrawal,
  decodeWithdrawal,
  getDepositoryDepositMessageId,
  getExecutionMessageId,
} from "@relay-protocol/settlement-sdk"

// Encode/decode withdrawal messages
const encoded = encodeWithdrawal(decodedWithdrawal)
const decoded = decodeWithdrawal(encoded, vmType)

// Get message IDs
const depositId = getDepositoryDepositMessageId(message)
const executionId = getExecutionMessageId(message)

Supported VM Types

• bitcoin-vm
• ethereum-vm
• solana-vm
• hyperliquid-vm
• ton-vm
• tron-vm
• lighter-vm

Adding a New VM

Withdrawal support for each VM lives in its own module under src/messages/v2.1/withdrawals/. To add a VM:

1. Add the VM to the VmType union in src/utils.ts.
2. Create src/messages/v2.1/withdrawals/<vm>.ts exporting a DecodedXxxVmWithdrawal type and a WithdrawalCodec implementation. For ABI-encoded payloads, declare the ABI parameters once with parseAbiParameters and build encode/decode with defineAbiWithdrawalCodec — the transforms are type-checked against the ABI schema, so the decoded type cannot drift from the encoding.
3. Register the codec in src/messages/v2.1/withdrawals/index.ts and add the type to the DecodedWithdrawal union (both are compile-enforced).
4. Add round-trip and pinned-vector tests in test/, ideally referencing the corresponding on-chain payload builder's test vectors.

API Reference

See the TypeScript definitions for complete API documentation.