Bridge: Full TypeScript Implementation

npm i viem @solana/web3.js @nktkas/hyperliquid

// bridge.ts — Mobula Bridge API client (Alpha Preview)
// Covers EVM, Solana, and HyperLiquid origins in one entry point.

import { createWalletClient, defineChain, http, type Hex, type PrivateKeyAccount } from "viem";
import { arbitrum, base, bsc, polygon, type Chain } from "viem/chains";
import {
  Connection,
  Keypair,
  PublicKey,
  SystemProgram,
  Transaction,
  TransactionInstruction,
  VersionedTransaction,
} from "@solana/web3.js";
import * as hl from "@nktkas/hyperliquid";

const API = "https://api.mobula.io";
const MEMO_PROGRAM = new PublicKey("MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr");

// Robinhood Chain (evm:4663) isn't in viem/chains — define it inline. It's a
// native-ETH-only chain (no canonical USDC), so it bridges via native + swap.
const robinhood = defineChain({
  id: 4663,
  name: "Robinhood Chain",
  nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
  rpcUrls: { default: { http: ["https://rpc.mainnet.chain.robinhood.com"] } },
});

const EVM_CHAINS: Record<number, Chain> = {
  8453: base,
  56: bsc,
  42161: arbitrum,
  137: polygon,
  4663: robinhood,
};

// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------

export interface QuoteParams {
  originChainId: string;          // "evm:8453" | "evm:56" | "evm:42161" | "evm:137" | "evm:4663" | "solana:solana" | "hl:mainnet"
  destinationChainId: string;
  amount: string;                  // human units, NOT wei (e.g. "0.05")
  walletAddress: string;           // destination recipient
  senderAddress?: string;          // origin sender (required for Solana SPL)
  originToken?: string;            // omit for native; EVM addresses are checksummed server-side
  destinationToken?: string;
  slippage?: string;               // percent, default "1", range 0..50
  destinationType?: string;        // destination account venue (e.g. HyperLiquid): "spot" (default) | "perps"
  originType?: string;             // origin account venue (e.g. HyperLiquid): "spot" (default) | "perps"
  feeBps?: string;                 // optional integrator fee in bps (0..500). Requires feeWallet.
  feeWallet?: string;              // integrator payout address — MUST be a DESTINATION-ecosystem address
}

export interface Signers {
  evm?: PrivateKeyAccount;                              // signs EVM origins
  solana?: { signer: Keypair; connection: Connection }; // signs Solana origins
  hl?: hl.ExchangeClient;                                // signs HyperLiquid origins
}

// ---------------------------------------------------------------------------
// 1) Quote
// ---------------------------------------------------------------------------

export async function getQuote(p: QuoteParams, apiKey: string) {
  // The API key goes in the query string (?apiKey=); an Authorization: Bearer
  // header also works on /quote. With neither, /quote returns
  // { error: "Missing required parameter: apiKey (or Authorization: Bearer <token>)" }.
  const params = new URLSearchParams({ ...(p as Record<string, string>), apiKey });
  const res = await fetch(`${API}/api/2/bridge/quote?${params}`);
  const json = await res.json();
  if (json.error) throw new Error(json.error);
  // For evm:* and hl:mainnet origins, json.data.signatureRequired is true and
  // json.data.typedData carries the EIP-712 payload the depositor must sign.
  // Until you commit the signature via confirmQuote, your signed intent is NOT
  // committed and the solver will not process the deposit.
  //
  // json.data also carries `recommendedSlippage` (% — sign with at least this or
  // the fill gets refunded; bridge() enforces it) and a `fees` breakdown.
  // `estimatedAmountOut` / `estimatedAmountOutUsd` are already net of every fee.
  return json.data;
}

// ---------------------------------------------------------------------------
// 1b) Sign the quote (EIP-712) and commit it server-side. EVM + HL only.
// ---------------------------------------------------------------------------

export async function signAndConfirmQuote(
  p: QuoteParams,
  quote: any,
  signer: PrivateKeyAccount,
  apiKey: string,
) {
  if (!quote.signatureRequired) return quote; // Solana origin — no sig needed.
  if (!quote.typedData) throw new Error("Quote missing typedData");

  const signature = await signer.signTypedData({
    domain: quote.typedData.domain,
    types: quote.typedData.types,
    primaryType: quote.typedData.primaryType,
    message: quote.typedData.message,
  });

  const params = new URLSearchParams({ ...(p as Record<string, string>), apiKey });
  params.set("intentId", quote.intentId);
  params.set("deadline", String(quote.deadline));
  params.set("minAmountOut", quote.typedData.message.minAmountOut);
  params.set("signature", signature);

  const res = await fetch(`${API}/api/2/bridge/quote?${params}`);
  const json = await res.json();
  if (json.error) throw new Error(json.error);
  return json.data; // prediction.persisted === true on success
}

// ---------------------------------------------------------------------------
// 2) Sign and broadcast the deposit (one helper per origin VM)
// ---------------------------------------------------------------------------

// EVM: optional approve step (ERC-20 origins) then the deposit TX.
async function signEvm(quote: any, account: PrivateKeyAccount): Promise<string> {
  const tx = quote.deposit.evm;
  const chain = EVM_CHAINS[tx.chainId];
  if (!chain) throw new Error(`Unsupported EVM chainId ${tx.chainId}`);
  const wallet = createWalletClient({ account, chain, transport: http() });

  const approve = quote.steps?.find((s: any) => s.type === "approve");
  if (approve) {
    // approvalAmount is MAX_UINT256 — one approve per (token, spender) lasts forever.
    // Skip this if the on-chain allowance already covers `amount`.
    await wallet.sendTransaction({
      to: approve.tx.to as Hex,
      data: approve.tx.data as Hex,
      value: BigInt(approve.tx.value),
    });
  }

  return wallet.sendTransaction({
    to: tx.to as Hex,
    data: tx.data as Hex,
    value: BigInt(tx.value),
  });
}

// Solana: native (transfer + memo carrying intent payload) or SPL (pre-built versioned TX).
async function signSolana(
  quote: any,
  signer: Keypair,
  connection: Connection,
): Promise<string> {
  const sol = quote.deposit.solana;

  if (sol.serializedTx) {
    // SPL: full versioned TX (transfer + ATA create if needed + memo) is pre-built server-side.
    const tx = VersionedTransaction.deserialize(Buffer.from(sol.serializedTx, "base64"));
    tx.sign([signer]);
    return connection.sendRawTransaction(tx.serialize());
  }

  // Native SOL: build SystemProgram.transfer + memo instruction ourselves.
  const tx = new Transaction()
    .add(
      SystemProgram.transfer({
        fromPubkey: signer.publicKey,
        toPubkey: new PublicKey(sol.to),
        lamports: BigInt(sol.amount),
      }),
    )
    .add(
      new TransactionInstruction({
        keys: [{ pubkey: signer.publicKey, isSigner: true, isWritable: true }],
        programId: MEMO_PROGRAM,
        data: Buffer.from(sol.memo),
      }),
    );
  tx.recentBlockhash = (await connection.getLatestBlockhash()).blockhash;
  tx.feePayer = signer.publicKey;
  tx.sign(signer);
  return connection.sendRawTransaction(tx.serialize());
}

// HyperLiquid: spotSend (spot wallet) or usdSend (perps/core USDC) to the solver
// L1 address via @nktkas/hyperliquid — the action matches deposit.hl.type, set by
// originType. usdSend is always USDC and carries no token.
async function signHyperliquid(quote: any, exchange: hl.ExchangeClient) {
  const dep = quote.deposit.hl; // { type: "spotSend" | "usdSend", to, token?, amount }
  const result =
    dep.type === "usdSend"
      ? await exchange.usdSend({ destination: dep.to, amount: dep.amount })
      : await exchange.spotSend({ destination: dep.to, token: dep.token, amount: dep.amount });
  if (result.status !== "ok") throw new Error(`HL ${dep.type} rejected: ${JSON.stringify(result)}`);
}

// ---------------------------------------------------------------------------
// 3) Wait for the fill — no client-side sleep, server already blocks.
// ---------------------------------------------------------------------------

export async function waitForFill(intentId: string, apiKey: string) {
  while (true) {
    const res = await fetch(`${API}/api/2/bridge/status/${intentId}/wait?apiKey=${apiKey}`);
    const { data } = await res.json();

    if (data.status === "filled" || data.status === "settled") return data;
    if (data.status === "failed" || data.status === "refunded") {
      throw new Error(`Bridge ${data.status}`);
    }
    // pending / filling / relaying — re-fire immediately
  }
}

// ---------------------------------------------------------------------------
// Unified entry point — dispatches on the deposit shape from /quote.
// ---------------------------------------------------------------------------

export async function bridge(
  params: QuoteParams,
  signers: Signers,
  apiKey: string,
) {
  let quote = await getQuote(params, apiKey);

  // Bump slippage to the quote's recommendation before committing. The solver
  // refunds any fill that lands below the signed minAmountOut (failure code
  // 'slippage'), so a tolerance under recommendedSlippage is a near-guaranteed
  // refund. recommendedSlippage = the quote's swap price impact + any
  // fee-on-transfer tax + a 1% drift buffer (2% floor on native-token
  // destinations). Re-quoting regenerates the typedData (EVM/HL) and the memo
  // minAmountOut (Solana) at the safe tolerance.
  const wantSlippage = Number(params.slippage ?? "1");
  if (quote.recommendedSlippage != null && wantSlippage < quote.recommendedSlippage) {
    params = { ...params, slippage: String(quote.recommendedSlippage) };
    quote = await getQuote(params, apiKey);
  }

  // EVM + HL origins: commit the quote via EIP-712 before broadcasting. The
  // solver rejects deposits whose signed intent has not been committed.
  if (quote.signatureRequired) {
    if (!signers.evm) {
      throw new Error("EVM signer required to sign the quote (EVM and HL origins use EVM keys)");
    }
    quote = await signAndConfirmQuote(params, quote, signers.evm, apiKey);
  }

  if (quote.deposit?.evm) {
    if (!signers.evm) throw new Error("EVM signer required for this route");
    const hash = await signEvm(quote, signers.evm);
    console.log(`deposit ${hash}`);
  } else if (quote.deposit?.solana) {
    if (!signers.solana) throw new Error("Solana signer required for this route");
    const sig = await signSolana(quote, signers.solana.signer, signers.solana.connection);
    console.log(`deposit ${sig}`);
  } else if (quote.deposit?.hl) {
    if (!signers.hl) throw new Error("HyperLiquid client required for this route");
    await signHyperliquid(quote, signers.hl);
  } else {
    throw new Error("Quote returned unknown deposit shape");
  }

  return waitForFill(quote.intentId, apiKey);
}

// usage.ts
import { privateKeyToAccount } from "viem/accounts";
import { Connection, Keypair } from "@solana/web3.js";
import * as hl from "@nktkas/hyperliquid";
import bs58 from "bs58";
import { bridge, type Signers } from "./bridge";

const API_KEY = process.env.MOBULA_API_KEY!;

// Shared signers — pass whichever ones are relevant for the routes you use.
const evmAccount = privateKeyToAccount(process.env.EVM_PK as `0x${string}`);
const solSigner = Keypair.fromSecretKey(bs58.decode(process.env.SOL_SK!));
const solConn = new Connection("https://api.mainnet-beta.solana.com");
const hlClient = new hl.ExchangeClient({
  wallet: evmAccount,                  // HL signs with an EVM key
  transport: new hl.HttpTransport(),
});

const signers: Signers = {
  evm: evmAccount,
  solana: { signer: solSigner, connection: solConn },
  hl: hlClient,
};

const SOL_ADDR = solSigner.publicKey.toBase58();
const EVM_ADDR = evmAccount.address;

// 1) Base ETH → Solana SOL (native → native, no approve)
const r1 = await bridge({
  originChainId: "evm:8453",
  destinationChainId: "solana:solana",
  amount: "0.05",
  walletAddress: SOL_ADDR,
  senderAddress: EVM_ADDR,
}, signers, API_KEY);
console.log("Base→Solana filled:", r1.fillTxHash, `(${r1.latencyMs}ms)`);

// 2) Solana SOL → Arbitrum ETH (Solana native origin, EVM destination)
const r2 = await bridge({
  originChainId: "solana:solana",
  destinationChainId: "evm:42161",
  amount: "0.5",
  walletAddress: EVM_ADDR,
  senderAddress: SOL_ADDR,
}, signers, API_KEY);
console.log("Solana→Arbitrum filled:", r2.fillTxHash, `(${r2.latencyMs}ms)`);

// 3) BSC USDT → Polygon USDC (ERC-20 → ERC-20 — exercises approve + swapAndBridge)
const r3 = await bridge({
  originChainId: "evm:56",
  destinationChainId: "evm:137",
  originToken: "0x55d398326f99059fF775485246999027B3197955",      // USDT on BSC
  destinationToken: "0x3c499c542cef5e3811e1192ce70d8cc03d5c3359", // USDC on Polygon
  amount: "10",
  walletAddress: EVM_ADDR,
  senderAddress: EVM_ADDR,
}, signers, API_KEY);
console.log("BSC USDT → Polygon USDC filled:", r3.fillTxHash);

// 4) Base USDC → Arbitrum USDC (direct-bridge token path — approve + bridgeToken, no swap)
const r4 = await bridge({
  originChainId: "evm:8453",
  destinationChainId: "evm:42161",
  originToken: "0x833589fcD6eDb6E08f4c7C32D4f71b54bdA02913",      // USDC on Base
  destinationToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", // USDC on Arbitrum
  amount: "25",
  walletAddress: EVM_ADDR,
  senderAddress: EVM_ADDR,
}, signers, API_KEY);
console.log("Base USDC → Arbitrum USDC filled:", r4.fillTxHash);

// 5) HyperLiquid USDC → Base ETH (HL spotSend → EVM destination; usdSend when originType=perps)
const r5 = await bridge({
  originChainId: "hl:mainnet",
  destinationChainId: "evm:8453",
  amount: "5",
  walletAddress: EVM_ADDR,
  senderAddress: EVM_ADDR,
}, signers, API_KEY);
console.log("HL → Base filled:", r5.fillTxHash, `(${r5.latencyMs}ms)`);

// 6) Base ETH → Robinhood Chain ETH (native → native on a native-only chain)
const r6 = await bridge({
  originChainId: "evm:8453",
  destinationChainId: "evm:4663",
  amount: "0.02",
  walletAddress: EVM_ADDR,
  senderAddress: EVM_ADDR,
}, signers, API_KEY);
console.log("Base → Robinhood filled:", r6.fillTxHash, `(${r6.latencyMs}ms)`);

// 7) Base USDC → Arbitrum USDC with a 30 bps integrator fee paid to feeWallet
//    (feeWallet is a DESTINATION-ecosystem address — 0x here since dest is EVM)
const r7 = await bridge({
  originChainId: "evm:8453",
  destinationChainId: "evm:42161",
  originToken: "0x833589fcD6eDb6E08f4c7C32D4f71b54bdA02913",      // USDC on Base
  destinationToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", // USDC on Arbitrum
  amount: "25",
  walletAddress: EVM_ADDR,
  senderAddress: EVM_ADDR,
  feeBps: "30",
  feeWallet: EVM_ADDR,
}, signers, API_KEY);
console.log("Base → Arbitrum (with integrator fee) filled:", r7.fillTxHash);