@arbilink/sdk 0.1.0

package/src/abi/Receiver.json

@@ -0,0 +1,211 @@
+[
+  {
+    "type": "constructor",
+    "inputs": [
+      { "name": "_messageHub",    "type": "address" },
+      { "name": "_hubSigningKey", "type": "address" }
+    ]
+  },
+  {
+    "type": "function",
+    "name": "receiveMessage",
+    "inputs": [
+      {
+        "name": "message",
+        "type": "tuple",
+        "components": [
+          { "name": "id",          "type": "uint256" },
+          { "name": "sender",      "type": "address" },
+          { "name": "target",      "type": "address" },
+          { "name": "data",        "type": "bytes"   },
+          { "name": "sourceChain", "type": "uint32"  }
+        ]
+      },
+      { "name": "proof", "type": "bytes" }
+    ],
+    "outputs": [{ "name": "success", "type": "bool" }],
+    "stateMutability": "nonpayable"
+  },
+  {
+    "type": "function",
+    "name": "proofPayload",
+    "inputs": [
+      {
+        "name": "message",
+        "type": "tuple",
+        "components": [
+          { "name": "id",          "type": "uint256" },
+          { "name": "sender",      "type": "address" },
+          { "name": "target",      "type": "address" },
+          { "name": "data",        "type": "bytes"   },
+          { "name": "sourceChain", "type": "uint32"  }
+        ]
+      }
+    ],
+    "outputs": [{ "name": "", "type": "bytes32" }],
+    "stateMutability": "pure"
+  },
+  {
+    "type": "function",
+    "name": "nonExecutionProofPayload",
+    "inputs": [
+      { "name": "messageId",        "type": "uint256" },
+      { "name": "destinationChain", "type": "uint32"  }
+    ],
+    "outputs": [{ "name": "", "type": "bytes32" }],
+    "stateMutability": "pure"
+  },
+  {
+    "type": "function",
+    "name": "setRelayer",
+    "inputs": [
+      { "name": "relayer",    "type": "address" },
+      { "name": "authorized", "type": "bool"    }
+    ],
+    "outputs": [],
+    "stateMutability": "nonpayable"
+  },
+  {
+    "type": "function",
+    "name": "setHubSigningKey",
+    "inputs": [{ "name": "newKey", "type": "address" }],
+    "outputs": [],
+    "stateMutability": "nonpayable"
+  },
+  {
+    "type": "function",
+    "name": "transferOwnership",
+    "inputs": [{ "name": "newOwner", "type": "address" }],
+    "outputs": [],
+    "stateMutability": "nonpayable"
+  },
+  {
+    "type": "function",
+    "name": "isProcessed",
+    "inputs": [
+      {
+        "name": "message",
+        "type": "tuple",
+        "components": [
+          { "name": "id",          "type": "uint256" },
+          { "name": "sender",      "type": "address" },
+          { "name": "target",      "type": "address" },
+          { "name": "data",        "type": "bytes"   },
+          { "name": "sourceChain", "type": "uint32"  }
+        ]
+      }
+    ],
+    "outputs": [{ "name": "", "type": "bool" }],
+    "stateMutability": "view"
+  },
+  {
+    "type": "function",
+    "name": "getReceipt",
+    "inputs": [
+      {
+        "name": "message",
+        "type": "tuple",
+        "components": [
+          { "name": "id",          "type": "uint256" },
+          { "name": "sender",      "type": "address" },
+          { "name": "target",      "type": "address" },
+          { "name": "data",        "type": "bytes"   },
+          { "name": "sourceChain", "type": "uint32"  }
+        ]
+      }
+    ],
+    "outputs": [
+      { "name": "executed",  "type": "bool"    },
+      { "name": "success",   "type": "bool"    },
+      { "name": "timestamp", "type": "uint256" }
+    ],
+    "stateMutability": "view"
+  },
+  {
+    "type": "function",
+    "name": "messageHub",
+    "inputs": [],
+    "outputs": [{ "name": "", "type": "address" }],
+    "stateMutability": "view"
+  },
+  {
+    "type": "function",
+    "name": "owner",
+    "inputs": [],
+    "outputs": [{ "name": "", "type": "address" }],
+    "stateMutability": "view"
+  },
+  {
+    "type": "function",
+    "name": "hubSigningKey",
+    "inputs": [],
+    "outputs": [{ "name": "", "type": "address" }],
+    "stateMutability": "view"
+  },
+  {
+    "type": "function",
+    "name": "authorizedRelayers",
+    "inputs": [{ "name": "", "type": "address" }],
+    "outputs": [{ "name": "", "type": "bool" }],
+    "stateMutability": "view"
+  },
+  {
+    "type": "function",
+    "name": "processedMessages",
+    "inputs": [{ "name": "", "type": "bytes32" }],
+    "outputs": [{ "name": "", "type": "bool" }],
+    "stateMutability": "view"
+  },
+  {
+    "type": "function",
+    "name": "totalExecuted",
+    "inputs": [],
+    "outputs": [{ "name": "", "type": "uint256" }],
+    "stateMutability": "view"
+  },
+  {
+    "type": "function",
+    "name": "totalFailed",
+    "inputs": [],
+    "outputs": [{ "name": "", "type": "uint256" }],
+    "stateMutability": "view"
+  },
+  {
+    "type": "event",
+    "name": "MessageReceived",
+    "inputs": [
+      { "name": "messageId", "type": "uint256", "indexed": true  },
+      { "name": "sender",    "type": "address", "indexed": true  },
+      { "name": "target",    "type": "address", "indexed": true  },
+      { "name": "success",   "type": "bool",    "indexed": false }
+    ]
+  },
+  {
+    "type": "event",
+    "name": "RelayerAuthorized",
+    "inputs": [
+      { "name": "relayer",    "type": "address", "indexed": true  },
+      { "name": "authorized", "type": "bool",    "indexed": false }
+    ]
+  },
+  {
+    "type": "event",
+    "name": "HubSigningKeyUpdated",
+    "inputs": [
+      { "name": "newKey", "type": "address", "indexed": true }
+    ]
+  },
+  {
+    "type": "event",
+    "name": "OwnershipTransferred",
+    "inputs": [
+      { "name": "previousOwner", "type": "address", "indexed": true },
+      { "name": "newOwner",      "type": "address", "indexed": true }
+    ]
+  },
+  { "type": "error", "name": "NotRelayer",       "inputs": [] },
+  { "type": "error", "name": "AlreadyProcessed", "inputs": [{ "name": "msgHash", "type": "bytes32" }] },
+  { "type": "error", "name": "InvalidSignature", "inputs": [] },
+  { "type": "error", "name": "InvalidTarget",    "inputs": [] },
+  { "type": "error", "name": "Unauthorized",     "inputs": [] }
+]

package/src/constants.ts

@@ -0,0 +1,60 @@
+import type { ChainConfig, ChainName } from './types';
+
+// ── Contract addresses ────────────────────────────────────────────────────────
+
+/** MessageHub deployed on Arbitrum Sepolia (421614) */
+export const MESSAGE_HUB_ADDRESS = '0x9a9e7Ec4EA29bb63fE7c38E124B253b44fF897Cc';
+
+/** ArbiLinkReceiver addresses on each destination chain */
+export const RECEIVER_ADDRESSES: Record<number, string> = {
+  11155111: '0x895058E57bBE8c84C2AABA5d61c4C739C5869F71', // Ethereum Sepolia
+  84532:    '0xD45efE42904C9a27630A548A1FB6d9F133Cf5D35', // Base Sepolia
+  80002:    '0x221B7Cca1C385C6c81e17b086C753328AF41AAAa', // Polygon Amoy
+};
+
+// ── Supported chains ──────────────────────────────────────────────────────────
+
+export const SUPPORTED_CHAINS: ChainConfig[] = [
+  {
+    id:              11155111,
+    name:            'Ethereum Sepolia',
+    shortName:       'ethereum',
+    rpc:             'https://sepolia.infura.io/v3/',
+    explorer:        'https://sepolia.etherscan.io',
+    receiverAddress: RECEIVER_ADDRESSES[11155111],
+  },
+  {
+    id:              84532,
+    name:            'Base Sepolia',
+    shortName:       'base',
+    rpc:             'https://sepolia.base.org',
+    explorer:        'https://sepolia.basescan.org',
+    receiverAddress: RECEIVER_ADDRESSES[84532],
+  },
+  {
+    id:              80002,
+    name:            'Polygon Amoy',
+    shortName:       'polygon',
+    rpc:             'https://rpc-amoy.polygon.technology',
+    explorer:        'https://amoy.polygonscan.com',
+    receiverAddress: RECEIVER_ADDRESSES[80002],
+  },
+];
+
+/** Map chain short-names to numeric IDs */
+export const CHAIN_IDS: Record<ChainName, number> = {
+  ethereum: 11155111, // Sepolia
+  base:     84532,    // Base Sepolia
+  polygon:  80002,    // Amoy testnet
+  optimism: 11155420, // Optimism Sepolia
+};
+
+// ── Challenge window ──────────────────────────────────────────────────────────
+
+/** Default challenge period in seconds (matches hub deployment param) */
+export const DEFAULT_CHALLENGE_PERIOD_SECS = 300; // 5 minutes
+
+// ── Arbitrum Sepolia hub chain ────────────────────────────────────────────────
+
+export const ARBITRUM_SEPOLIA_CHAIN_ID = 421614;
+export const ARBITRUM_SEPOLIA_RPC = 'https://sepolia-rollup.arbitrum.io/rpc';

package/src/index.ts

@@ -0,0 +1,41 @@
+// Main SDK class
+export { ArbiLink } from './ArbiLink';
+
+// Types
+export type {
+  ChainId,
+  ChainName,
+  ChainConfig,
+  Message,
+  MessageStatus,
+  RelayerInfo,
+  SendMessageParams,
+  WatchOptions,
+} from './types';
+export { ArbiLinkError } from './types';
+
+// Utilities
+export {
+  encodeCall,
+  formatMessageId,
+  formatEth,
+  statusLabel,
+  resolveChainId,
+  estimateDeliveryTime,
+  parseStatusCode,
+} from './utils';
+
+// Constants
+export {
+  MESSAGE_HUB_ADDRESS,
+  RECEIVER_ADDRESSES,
+  SUPPORTED_CHAINS,
+  CHAIN_IDS,
+  ARBITRUM_SEPOLIA_CHAIN_ID,
+  ARBITRUM_SEPOLIA_RPC,
+  DEFAULT_CHALLENGE_PERIOD_SECS,
+} from './constants';
+
+// ABIs (useful for integrators building their own wrappers)
+export { default as MessageHubABI } from './abi/MessageHub.json';
+export { default as ReceiverABI }   from './abi/Receiver.json';

package/src/types.ts

@@ -0,0 +1,82 @@
+// ── Chain types ───────────────────────────────────────────────────────────────
+
+export type ChainId = 11155111 | 84532 | 80002 | 11155420;
+
+export type ChainName = 'ethereum' | 'base' | 'polygon' | 'optimism';
+
+export interface ChainConfig {
+  id: number;
+  name: string;
+  shortName: ChainName;
+  rpc: string;
+  explorer: string;
+  receiverAddress: string;
+}
+
+// ── Message types ─────────────────────────────────────────────────────────────
+
+/** On-chain status codes (matches STATUS_* constants in MessageHub) */
+export type MessageStatus = 'pending' | 'relayed' | 'confirmed' | 'failed';
+
+/** Full message record as returned by the SDK */
+export interface Message {
+  id: bigint;
+  status: MessageStatus;
+  /** Sender address — populated from MessageSent event logs */
+  sender?: string;
+  /** Destination chain ID — populated from MessageSent event logs */
+  destinationChain?: number;
+  /** Target contract on the destination chain */
+  target?: string;
+  /** Encoded calldata for the target */
+  data?: string;
+  /** Protocol fee paid (in wei) — populated from MessageSent event logs */
+  feePaid?: bigint;
+  /** Relayer address, present once a relayer confirms delivery */
+  relayer?: string;
+}
+
+// ── SDK parameter types ───────────────────────────────────────────────────────
+
+export interface SendMessageParams {
+  /** Destination chain – either a numeric chain ID or a supported chain name */
+  to: number | ChainName;
+  /** Target contract address on the destination chain */
+  target: string;
+  /** ABI-encoded function call (use encodeCall() from utils) */
+  data: string;
+  /** Override the auto-calculated fee (wei). Fetched from hub if omitted. */
+  fee?: bigint;
+}
+
+export interface WatchOptions {
+  /** Poll interval in ms when WebSocket is unavailable (default: 3000) */
+  pollIntervalMs?: number;
+}
+
+// ── Relayer types ─────────────────────────────────────────────────────────────
+
+export interface RelayerInfo {
+  active: boolean;
+  stake: bigint;
+}
+
+// ── Error ─────────────────────────────────────────────────────────────────────
+
+export class ArbiLinkError extends Error {
+  constructor(
+    message: string,
+    public readonly cause?: unknown,
+  ) {
+    super(message);
+    this.name = 'ArbiLinkError';
+    // Preserve prototype chain in compiled JS
+    Object.setPrototypeOf(this, ArbiLinkError.prototype);
+  }
+
+  static from(err: unknown, context: string): ArbiLinkError {
+    if (err instanceof ArbiLinkError) return err;
+    const detail = err instanceof Error ? err.message : String(err);
+    return new ArbiLinkError(`${context}: ${detail}`, err);
+  }
+}

package/src/utils.ts

@@ -0,0 +1,111 @@
+import { encodeFunctionData, type Abi } from 'viem';
+import type { MessageStatus } from './types';
+import { CHAIN_IDS } from './constants';
+
+// ── Encoding helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Encode a contract function call into hex calldata ready for cross-chain delivery.
+ *
+ * @example
+ * ```typescript
+ * const data = encodeCall({
+ *   abi: parseAbi(['function mint(address to, uint256 amount)']),
+ *   functionName: 'mint',
+ *   args: ['0x742d35Cc...', 1000n],
+ * });
+ * ```
+ */
+export function encodeCall(params: {
+  abi: Abi;
+  functionName: string;
+  args?: readonly unknown[];
+}): string {
+  return encodeFunctionData({
+    abi:          params.abi,
+    functionName: params.functionName,
+    args:         params.args ?? [],
+  }) as string;
+}
+
+// ── Formatting ────────────────────────────────────────────────────────────────
+
+/**
+ * Format a numeric message ID as a zero-padded string.
+ * @example formatMessageId(42n) → "#000042"
+ */
+export function formatMessageId(id: bigint): string {
+  return `#${id.toString().padStart(6, '0')}`;
+}
+
+/**
+ * Human-readable label for a message status.
+ */
+export function statusLabel(status: MessageStatus): string {
+  const labels: Record<MessageStatus, string> = {
+    pending:   'Pending',
+    relayed:   'Relayed (in challenge window)',
+    confirmed: 'Confirmed',
+    failed:    'Failed',
+  };
+  return labels[status];
+}
+
+// ── Chain helpers ─────────────────────────────────────────────────────────────
+
+/**
+ * Resolve a chain name or numeric ID to a numeric chain ID.
+ * Throws `ArbiLinkError` for unknown chains.
+ */
+export function resolveChainId(chain: number | string): number {
+  if (typeof chain === 'number') return chain;
+
+  const id = CHAIN_IDS[chain.toLowerCase() as keyof typeof CHAIN_IDS];
+  if (id == null) {
+    throw new Error(
+      `Unknown chain "${chain}". Supported names: ${Object.keys(CHAIN_IDS).join(', ')}`,
+    );
+  }
+  return id;
+}
+
+/**
+ * Estimate message delivery time in seconds for a given destination chain.
+ *
+ * This is a rough heuristic based on block times – actual delivery depends on
+ * relayer availability and the 5-minute challenge window.
+ */
+export function estimateDeliveryTime(chainId: number): number {
+  const CHALLENGE_WINDOW = 300; // 5 min in seconds
+
+  const FINALITY_TIMES: Record<number, number> = {
+    11155111: 15,  // Ethereum Sepolia
+    84532:    2,   // Base Sepolia
+    80002:    2,   // Polygon Amoy
+    11155420: 2,   // Optimism Sepolia
+  };
+
+  return CHALLENGE_WINDOW + (FINALITY_TIMES[chainId] ?? 12);
+}
+
+// ── Status helpers ────────────────────────────────────────────────────────────
+
+const STATUS_MAP: MessageStatus[] = ['pending', 'relayed', 'confirmed', 'failed'];
+
+/**
+ * Convert the on-chain numeric status code to the SDK string representation.
+ */
+export function parseStatusCode(code: number): MessageStatus {
+  return STATUS_MAP[code] ?? 'pending';
+}
+
+// ── Wei helpers ───────────────────────────────────────────────────────────────
+
+/**
+ * Format a wei value as a human-readable ETH string.
+ * @example formatEth(1_000_000_000_000_000n) → "0.001 ETH"
+ */
+export function formatEth(wei: bigint): string {
+  const eth = Number(wei) / 1e18;
+  return `${eth.toFixed(6).replace(/\.?0+$/, '')} ETH`;
+}