nara-sdk 1.0.74 → 1.0.75

package/README.md

@@ -11,7 +11,7 @@
 
 ---
 
-TypeScript/JavaScript SDK for interacting with the Nara blockchain. Build agents, submit transactions, query accounts, and integrate with on-chain programs.
+TypeScript/JavaScript SDK for interacting with the Nara blockchain. Build agents, submit transactions, query accounts, cross-chain bridge, and integrate with on-chain programs.
 
 ## Install
 
@@ -19,29 +19,162 @@ TypeScript/JavaScript SDK for interacting with the Nara blockchain. Build agents
 npm install nara-sdk
 ```
 
+## Features
+
+- **Agent Registry** — Register agents, bind Twitter, submit tweets, verify, referral system
+- **Quest (PoMI)** — Proof of Machine Intelligence ZK quest system, stake, answer-to-earn
+- **Skills Hub** — On-chain skill registry for AI agents, upload/query skill content
+- **ZK ID** — Zero-knowledge anonymous identity, deposit, withdraw, ownership proofs
+- **Cross-chain Bridge** — Nara ↔ Solana bridge via Hyperlane warp routes (USDC, SOL), with in-tx fee extraction and validator signature tracking
+
 ## Quick Start
 
-```js
-import { Connection, Keypair, Transaction } from 'nara-sdk';
+```ts
+import { Connection, Keypair } from '@solana/web3.js';
+import { getQuestInfo, submitAnswer, generateProof } from 'nara-sdk';
 
 const connection = new Connection('https://mainnet-api.nara.build');
-const balance = await connection.getBalance(publicKey);
 ```
 
-## Features
+## Cross-chain Bridge
+
+Bridge tokens between Solana and Nara with built-in 0.5% fee extraction.
+
+### One-step bridge
+
+```ts
+import { Connection, Keypair } from '@solana/web3.js';
+import { bridgeTransfer, setAltAddress } from 'nara-sdk';
+
+const solanaConn = new Connection('https://api.mainnet-beta.solana.com');
+
+// Disable Nara ALT when sending from Solana
+setAltAddress(null);
+
+const result = await bridgeTransfer(solanaConn, wallet, {
+  token: 'USDC',            // 'USDC' | 'SOL'
+  fromChain: 'solana',      // 'solana' | 'nara'
+  recipient: targetPubkey,  // destination chain address
+  amount: 1_000_000n,       // raw units (1 USDC = 1_000_000)
+});
 
+console.log(result.signature);    // source chain tx
+console.log(result.messageId);    // cross-chain message ID (0x...)
+console.log(result.feeAmount);    // fee deducted
+console.log(result.bridgeAmount); // net amount bridged
 ```
-Transactions       Build, sign, and send transactions
-Accounts           Query balances, token accounts, and program state
-Programs           Interact with Nara on-chain programs (Agent Registry, PoMI, ZK ID)
-Keypairs           Generate and manage wallet keypairs
-RPC Client         Full RPC method coverage
+
+### Build instructions for relay
+
+```ts
+import { makeBridgeIxs } from 'nara-sdk';
+
+const { instructions, uniqueMessageKeypair, feeAmount, bridgeAmount } =
+  makeBridgeIxs({
+    token: 'USDC',
+    fromChain: 'solana',
+    sender: userPubkey,
+    recipient: targetPubkey,
+    amount: 1_000_000n,
+  });
+
+// uniqueMessageKeypair must sign the tx
 ```
 
-## CLI
+### Track cross-chain message
 
-```bash
-npx nara-sdk --help
+```ts
+import {
+  extractMessageId,
+  queryMessageSignatures,
+  queryMessageStatus,
+} from 'nara-sdk';
+
+// 1. Extract message ID from source tx
+const messageId = await extractMessageId(connection, signature);
+
+// 2. Query validator signatures (3-way parallel scan on S3)
+const sigs = await queryMessageSignatures(messageId, 'solana');
+console.log(sigs.signedCount, '/', sigs.totalValidators); // e.g. 3/3
+console.log(sigs.fullySigned);                             // true
+
+// 3. Check delivery on destination chain
+const status = await queryMessageStatus(naraConn, messageId, 'nara');
+console.log(status.delivered);          // true
+console.log(status.deliverySignature);  // destination tx
+```
+
+### Supported tokens
+
+| Token | Solana side | Nara side | Decimals |
+|---|---|---|---|
+| USDC | collateral (lock) | synthetic (mint, Token-2022) | 6 |
+| SOL | native (lamports) | synthetic (mint, Token-2022) | 9 |
+
+Add new tokens at runtime:
+
+```ts
+import { registerBridgeToken } from 'nara-sdk';
+
+registerBridgeToken('USDT', {
+  symbol: 'USDT',
+  decimals: 6,
+  solana: { warpProgram, mode: 'collateral', mint, tokenProgram },
+  nara: { warpProgram, mode: 'synthetic', mint, tokenProgram },
+});
+```
+
+### Fee configuration
+
+Default fee: **0.5%** (50 bps), deducted from the bridged amount on the source chain.
+
+```ts
+import { setBridgeFeeRecipient } from 'nara-sdk';
+
+// Override fee recipient at runtime
+setBridgeFeeRecipient('YourFeeRecipientPubkey...');
+
+// Or per-call
+await bridgeTransfer(conn, wallet, {
+  ...params,
+  feeBps: 100,                      // 1%
+  feeRecipient: customPubkey,       // override
+  skipFee: true,                    // or skip entirely
+});
+```
+
+## Agent Registry
+
+```ts
+import {
+  registerAgent,
+  getAgentRecord,
+  setTwitter,
+  verifyTwitter,
+  submitTweet,
+  approveTweet,
+} from 'nara-sdk';
+
+// Register an agent
+await registerAgent(connection, wallet, agentId, name, metadataUri);
+
+// Twitter verification flow
+await setTwitter(connection, wallet, agentId, handle);
+await verifyTwitter(connection, verifierWallet, agentId);
+
+// Tweet submission & approval
+await submitTweet(connection, wallet, agentId, tweetId, tweetUrl);
+await approveTweet(connection, verifierWallet, agentId, tweetId, freeCredits);
+```
+
+## Quest (PoMI)
+
+```ts
+import { getQuestInfo, generateProof, submitAnswer } from 'nara-sdk';
+
+const quest = await getQuestInfo(connection);
+const proof = await generateProof(quest.question, answer);
+const sig = await submitAnswer(connection, wallet, proof);
 ```
 
 ## Documentation

package/index.ts

@@ -15,6 +15,9 @@ export {
   DEFAULT_ZKID_PROGRAM_ID,
   DEFAULT_AGENT_REGISTRY_PROGRAM_ID,
   DEFAULT_ALT_ADDRESS,
+  DEFAULT_BRIDGE_FEE_BPS,
+  DEFAULT_BRIDGE_FEE_RECIPIENT,
+  BRIDGE_FEE_BPS_DENOMINATOR,
 } from "./src/constants";
 
 // Export signing utilities
@@ -165,6 +168,52 @@ export {
   type AgentRegistryOptions,
 } from "./src/agent_registry";
 
+// Export bridge functions and types
+export {
+  // Constants
+  SOLANA_DOMAIN,
+  NARA_DOMAIN,
+  SOLANA_MAILBOX,
+  NARA_MAILBOX,
+  SPL_NOOP,
+  BRIDGE_TOKENS,
+  // Token registry
+  registerBridgeToken,
+  // Fee recipient runtime override
+  setBridgeFeeRecipient,
+  getBridgeFeeRecipient,
+  // PDA helpers
+  deriveOutboxPda,
+  deriveDispatchAuthorityPda,
+  deriveDispatchedMessagePda,
+  deriveTokenPda,
+  deriveEscrowPda,
+  deriveNativeCollateralPda,
+  // Encoders
+  encodeTransferRemote,
+  // Fee + ix builders
+  calculateBridgeFee,
+  makeBridgeFeeIxs,
+  makeTransferRemoteIx,
+  makeBridgeIxs,
+  // High level
+  bridgeTransfer,
+  extractMessageId,
+  queryMessageStatus,
+  queryMessageSignatures,
+  type BridgeChain,
+  type BridgeMode,
+  type BridgeTokenSide,
+  type BridgeTokenConfig,
+  type BridgeTransferParams,
+  type BridgeIxsResult,
+  type BridgeTransferResult,
+  type FeeSplit,
+  type MessageStatus,
+  type ValidatorSignature,
+  type MessageSignatureStatus,
+} from "./src/bridge";
+
 // Export IDLs and types
 export { default as NaraQuestIDL } from "./src/idls/nara_quest.json";
 export { default as NaraSkillsHubIDL } from "./src/idls/nara_skills_hub.json";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nara-sdk",
-  "version": "1.0.74",
+  "version": "1.0.75",
   "description": "SDK for the Nara chain (Solana-compatible)",
   "module": "index.ts",
   "main": "index.ts",

package/src/bridge.ts

@@ -0,0 +1,780 @@
+/**
+ * Cross-chain bridge SDK between Nara and Solana via Hyperlane warp routes.
+ *
+ * Supports two assets out of the box (USDC, SOL) in both directions, with
+ * an in-tx fee deduction (default 0.5%) sent to BRIDGE_FEE_RECIPIENT.
+ *
+ * Adding a new asset:
+ *   1. Append a new entry to BRIDGE_TOKENS with {symbol, decimals, solana, nara}.
+ *   2. The PDA derivation, account-list construction, and instruction encoding
+ *      are mode-driven (collateral / synthetic / native), no per-token code paths.
+ */
+
+import {
+  Connection,
+  Keypair,
+  PublicKey,
+  SystemProgram,
+  TransactionInstruction,
+} from "@solana/web3.js";
+import {
+  createAssociatedTokenAccountIdempotentInstruction,
+  createTransferCheckedInstruction,
+  getAssociatedTokenAddressSync,
+  TOKEN_2022_PROGRAM_ID,
+  TOKEN_PROGRAM_ID,
+} from "@solana/spl-token";
+import {
+  BRIDGE_FEE_BPS_DENOMINATOR,
+  DEFAULT_BRIDGE_FEE_BPS,
+  DEFAULT_BRIDGE_FEE_RECIPIENT,
+} from "./constants";
+import { sendTx } from "./tx";
+
+// ─── Types ────────────────────────────────────────────────────────
+
+export type BridgeChain = "solana" | "nara";
+export type BridgeMode = "collateral" | "synthetic" | "native";
+
+export interface BridgeTokenSide {
+  warpProgram: PublicKey;
+  mode: BridgeMode;
+  /** SPL mint pubkey. null for Solana native SOL. */
+  mint: PublicKey | null;
+  /** SPL token program. null for Solana native SOL. */
+  tokenProgram: PublicKey | null;
+}
+
+export interface BridgeTokenConfig {
+  symbol: string;
+  decimals: number;
+  solana: BridgeTokenSide;
+  nara: BridgeTokenSide;
+}
+
+export interface BridgeTransferParams {
+  /** Token symbol from BRIDGE_TOKENS (e.g. "USDC", "SOL") */
+  token: string;
+  /** Source chain — fee is deducted on this chain in the source token */
+  fromChain: BridgeChain;
+  /** Sender pubkey on the source chain */
+  sender: PublicKey;
+  /** Recipient pubkey on the destination chain */
+  recipient: PublicKey;
+  /** Gross amount (raw units, source-chain decimals). Fee is deducted from this. */
+  amount: bigint;
+  /** Optional fee bps override (defaults to BRIDGE_FEE_BPS) */
+  feeBps?: number;
+  /** Optional fee recipient override (defaults to BRIDGE_FEE_RECIPIENT) */
+  feeRecipient?: PublicKey;
+  /** Skip fee deduction entirely */
+  skipFee?: boolean;
+}
+
+export interface BridgeIxsResult {
+  /** All instructions in order: [feeIx?, atapayerIx?, transferRemoteIx] */
+  instructions: TransactionInstruction[];
+  /** Extra signer required by the transferRemote ix (the unique message keypair) */
+  uniqueMessageKeypair: Keypair;
+  /** Fee deducted in source token raw units */
+  feeAmount: bigint;
+  /** Net amount actually bridged */
+  bridgeAmount: bigint;
+}
+
+export interface BridgeTransferResult {
+  signature: string;
+  messageId: string | null;
+  feeAmount: bigint;
+  bridgeAmount: bigint;
+}
+
+// ─── Chain constants ───────────────────────────────────────────────
+
+export const SOLANA_DOMAIN = 1399811149;
+export const NARA_DOMAIN = 40778959;
+
+export const SOLANA_MAILBOX = new PublicKey(
+  "E588QtVUvresuXq2KoNEwAmoifCzYGpRBdHByN9KQMbi"
+);
+export const NARA_MAILBOX = new PublicKey(
+  "EjtLD3MCBJregFKAce2pQqPtSnnmBWK5oAZ3wBifHnaH"
+);
+
+export const SPL_NOOP = new PublicKey(
+  "noopb9bkMVfRPU8AsbpTUg8AQkHtKwMYZiFUjNRtMmV"
+);
+
+function mailboxFor(chain: BridgeChain): PublicKey {
+  return chain === "solana" ? SOLANA_MAILBOX : NARA_MAILBOX;
+}
+
+function destinationDomainFor(toChain: BridgeChain): number {
+  return toChain === "solana" ? SOLANA_DOMAIN : NARA_DOMAIN;
+}
+
+// ─── Token registry ───────────────────────────────────────────────
+
+export const BRIDGE_TOKENS: Record<string, BridgeTokenConfig> = {
+  USDC: {
+    symbol: "USDC",
+    decimals: 6,
+    solana: {
+      warpProgram: new PublicKey("4GcZJTa8s9vxtTz97Vj1RrwKMqPkT3DiiJkvUQDwsuZP"),
+      mode: "collateral",
+      mint: new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"),
+      tokenProgram: TOKEN_PROGRAM_ID,
+    },
+    nara: {
+      warpProgram: new PublicKey("BC2j6WrdPs9xhU9CfBwJsYSnJrGq5Tcm4SEen9ENv7go"),
+      mode: "synthetic",
+      mint: new PublicKey("8P7UGWjq86N3WUmwEgKeGHJZLcoMJqr5jnRUmeBN7YwR"),
+      tokenProgram: TOKEN_2022_PROGRAM_ID,
+    },
+  },
+  SOL: {
+    symbol: "SOL",
+    decimals: 9,
+    solana: {
+      warpProgram: new PublicKey("46MmAWwKRAt9uvn7m44NXbVq2DCWBQE2r1TDw25nyXrt"),
+      mode: "native",
+      mint: null,
+      tokenProgram: null,
+    },
+    nara: {
+      warpProgram: new PublicKey("6bKmjEMbjcJUnqAiNw7AXuMvUALzw5XRKiV9dBsterxg"),
+      mode: "synthetic",
+      mint: new PublicKey("7fKh7DqPZmsYPHdGvt9Qw2rZkSEGp9F5dBa3XuuuhavU"),
+      tokenProgram: TOKEN_2022_PROGRAM_ID,
+    },
+  },
+};
+
+/** Register a new bridge token at runtime */
+export function registerBridgeToken(symbol: string, config: BridgeTokenConfig): void {
+  BRIDGE_TOKENS[symbol] = config;
+}
+
+function getToken(symbol: string): BridgeTokenConfig {
+  const t = BRIDGE_TOKENS[symbol];
+  if (!t) throw new Error(`Unknown bridge token: ${symbol}`);
+  return t;
+}
+
+// ─── Fee recipient (runtime override) ─────────────────────────────
+
+let _feeRecipientOverride: PublicKey | null = null;
+
+/** Override the bridge fee recipient at runtime */
+export function setBridgeFeeRecipient(recipient: PublicKey | string | null): void {
+  if (recipient === null) {
+    _feeRecipientOverride = null;
+    return;
+  }
+  _feeRecipientOverride =
+    typeof recipient === "string" ? new PublicKey(recipient) : recipient;
+}
+
+export function getBridgeFeeRecipient(): PublicKey {
+  if (_feeRecipientOverride) return _feeRecipientOverride;
+  return new PublicKey(DEFAULT_BRIDGE_FEE_RECIPIENT);
+}
+
+// ─── PDA derivation ───────────────────────────────────────────────
+
+export function deriveOutboxPda(mailbox: PublicKey): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [Buffer.from("hyperlane"), Buffer.from("-"), Buffer.from("outbox")],
+    mailbox
+  );
+  return pda;
+}
+
+export function deriveDispatchAuthorityPda(warpProgram: PublicKey): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [
+      Buffer.from("hyperlane_dispatcher"),
+      Buffer.from("-"),
+      Buffer.from("dispatch_authority"),
+    ],
+    warpProgram
+  );
+  return pda;
+}
+
+export function deriveDispatchedMessagePda(
+  mailbox: PublicKey,
+  uniqueMessagePubkey: PublicKey
+): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [
+      Buffer.from("hyperlane"),
+      Buffer.from("-"),
+      Buffer.from("dispatched_message"),
+      Buffer.from("-"),
+      uniqueMessagePubkey.toBuffer(),
+    ],
+    mailbox
+  );
+  return pda;
+}
+
+export function deriveTokenPda(warpProgram: PublicKey): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [
+      Buffer.from("hyperlane_message_recipient"),
+      Buffer.from("-"),
+      Buffer.from("handle"),
+      Buffer.from("-"),
+      Buffer.from("account_metas"),
+    ],
+    warpProgram
+  );
+  return pda;
+}
+
+export function deriveEscrowPda(warpProgram: PublicKey): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [
+      Buffer.from("hyperlane_token"),
+      Buffer.from("-"),
+      Buffer.from("escrow"),
+    ],
+    warpProgram
+  );
+  return pda;
+}
+
+export function deriveNativeCollateralPda(warpProgram: PublicKey): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [
+      Buffer.from("hyperlane_token"),
+      Buffer.from("-"),
+      Buffer.from("native_collateral"),
+    ],
+    warpProgram
+  );
+  return pda;
+}
+
+// ─── Instruction data encoder ─────────────────────────────────────
+
+/**
+ * Encodes a TransferRemote instruction body.
+ * Layout:
+ *   [9 bytes prefix 0x01*9] [4 bytes destinationDomain u32 LE]
+ *   [32 bytes recipient]    [32 bytes amount as U256 LE]
+ */
+export function encodeTransferRemote(
+  destinationDomain: number,
+  recipient: PublicKey,
+  amount: bigint
+): Buffer {
+  const buf = Buffer.alloc(9 + 4 + 32 + 32);
+  for (let i = 0; i < 9; i++) buf[i] = 0x01;
+  buf.writeUInt32LE(destinationDomain, 9);
+  recipient.toBuffer().copy(buf, 13);
+  buf.writeBigUInt64LE(amount, 45);
+  return buf;
+}
+
+// ─── Fee calculation ──────────────────────────────────────────────
+
+export interface FeeSplit {
+  feeAmount: bigint;
+  bridgeAmount: bigint;
+  feeBps: number;
+}
+
+export function calculateBridgeFee(amount: bigint, feeBps?: number): FeeSplit {
+  const bps = feeBps ?? DEFAULT_BRIDGE_FEE_BPS;
+  if (bps < 0 || bps > BRIDGE_FEE_BPS_DENOMINATOR) {
+    throw new Error(`Invalid feeBps: ${bps}`);
+  }
+  const feeAmount = (amount * BigInt(bps)) / BigInt(BRIDGE_FEE_BPS_DENOMINATOR);
+  const bridgeAmount = amount - feeAmount;
+  return { feeAmount, bridgeAmount, feeBps: bps };
+}
+
+// ─── Fee instruction builder ──────────────────────────────────────
+
+/**
+ * Build the fee-collection instructions on the source chain in the source token.
+ *
+ * For SPL tokens: returns [createIdempotentATA(feeRecipient), transferChecked].
+ * For native SOL on Solana: returns [SystemProgram.transfer].
+ *
+ * Returns empty array if feeAmount == 0.
+ */
+export function makeBridgeFeeIxs(params: {
+  token: string;
+  fromChain: BridgeChain;
+  sender: PublicKey;
+  feeRecipient: PublicKey;
+  feeAmount: bigint;
+}): TransactionInstruction[] {
+  const { token, fromChain, sender, feeRecipient, feeAmount } = params;
+  if (feeAmount === 0n) return [];
+
+  const tokenCfg = getToken(token);
+  const side = tokenCfg[fromChain];
+
+  // Native SOL → SystemProgram.transfer
+  if (side.mode === "native") {
+    return [
+      SystemProgram.transfer({
+        fromPubkey: sender,
+        toPubkey: feeRecipient,
+        lamports: feeAmount,
+      }),
+    ];
+  }
+
+  // SPL token (collateral or synthetic) → ensure recipient ATA + transferChecked
+  if (!side.mint || !side.tokenProgram) {
+    throw new Error(`Token ${token} on ${fromChain} missing mint/tokenProgram`);
+  }
+
+  const senderAta = getAssociatedTokenAddressSync(
+    side.mint,
+    sender,
+    false,
+    side.tokenProgram
+  );
+  const recipientAta = getAssociatedTokenAddressSync(
+    side.mint,
+    feeRecipient,
+    true, // allowOwnerOffCurve — fee recipient may be a PDA
+    side.tokenProgram
+  );
+
+  return [
+    createAssociatedTokenAccountIdempotentInstruction(
+      sender,
+      recipientAta,
+      feeRecipient,
+      side.mint,
+      side.tokenProgram
+    ),
+    createTransferCheckedInstruction(
+      senderAta,
+      side.mint,
+      recipientAta,
+      sender,
+      feeAmount,
+      tokenCfg.decimals,
+      [],
+      side.tokenProgram
+    ),
+  ];
+}
+
+// ─── TransferRemote instruction builder ───────────────────────────
+
+/**
+ * Build the warp route TransferRemote instruction for a given token+direction.
+ * The unique message keypair must be passed in (it's a required tx signer).
+ */
+export function makeTransferRemoteIx(params: {
+  token: string;
+  fromChain: BridgeChain;
+  sender: PublicKey;
+  recipient: PublicKey;
+  amount: bigint;
+  uniqueMessageKeypair: Keypair;
+}): TransactionInstruction {
+  const { token, fromChain, sender, recipient, amount, uniqueMessageKeypair } =
+    params;
+
+  const tokenCfg = getToken(token);
+  const side = tokenCfg[fromChain];
+  const toChain: BridgeChain = fromChain === "solana" ? "nara" : "solana";
+
+  const mailbox = mailboxFor(fromChain);
+  const tokenPda = deriveTokenPda(side.warpProgram);
+  const dispatchAuthPda = deriveDispatchAuthorityPda(side.warpProgram);
+  const outboxPda = deriveOutboxPda(mailbox);
+  const dispatchedMsgPda = deriveDispatchedMessagePda(
+    mailbox,
+    uniqueMessageKeypair.publicKey
+  );
+
+  // First 9 accounts are common to all modes
+  const keys = [
+    { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+    { pubkey: SPL_NOOP, isSigner: false, isWritable: false },
+    { pubkey: tokenPda, isSigner: false, isWritable: false },
+    { pubkey: mailbox, isSigner: false, isWritable: false },
+    { pubkey: outboxPda, isSigner: false, isWritable: true },
+    { pubkey: dispatchAuthPda, isSigner: false, isWritable: false },
+    { pubkey: sender, isSigner: true, isWritable: true },
+    { pubkey: uniqueMessageKeypair.publicKey, isSigner: true, isWritable: false },
+    { pubkey: dispatchedMsgPda, isSigner: false, isWritable: true },
+  ];
+
+  // Plugin-specific accounts
+  if (side.mode === "collateral") {
+    if (!side.mint || !side.tokenProgram) {
+      throw new Error(`Collateral mode requires mint+tokenProgram for ${token}`);
+    }
+    const senderAta = getAssociatedTokenAddressSync(
+      side.mint,
+      sender,
+      false,
+      side.tokenProgram
+    );
+    const escrowPda = deriveEscrowPda(side.warpProgram);
+    keys.push(
+      { pubkey: side.tokenProgram, isSigner: false, isWritable: false },
+      { pubkey: side.mint, isSigner: false, isWritable: true },
+      { pubkey: senderAta, isSigner: false, isWritable: true },
+      { pubkey: escrowPda, isSigner: false, isWritable: true }
+    );
+  } else if (side.mode === "synthetic") {
+    if (!side.mint || !side.tokenProgram) {
+      throw new Error(`Synthetic mode requires mint+tokenProgram for ${token}`);
+    }
+    const senderAta = getAssociatedTokenAddressSync(
+      side.mint,
+      sender,
+      false,
+      side.tokenProgram
+    );
+    keys.push(
+      { pubkey: side.tokenProgram, isSigner: false, isWritable: false },
+      { pubkey: side.mint, isSigner: false, isWritable: true },
+      { pubkey: senderAta, isSigner: false, isWritable: true }
+    );
+  } else if (side.mode === "native") {
+    const nativeCollateralPda = deriveNativeCollateralPda(side.warpProgram);
+    keys.push(
+      { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+      { pubkey: nativeCollateralPda, isSigner: false, isWritable: true }
+    );
+  }
+
+  const data = encodeTransferRemote(destinationDomainFor(toChain), recipient, amount);
+
+  return new TransactionInstruction({
+    programId: side.warpProgram,
+    keys,
+    data,
+  });
+}
+
+// ─── High-level: build full bridge instruction set ────────────────
+
+/**
+ * Build all instructions needed to bridge tokens cross-chain with in-tx fee.
+ * Returns the instructions, the unique-message keypair (must sign the tx),
+ * and the fee/bridge amounts.
+ */
+export function makeBridgeIxs(params: BridgeTransferParams): BridgeIxsResult {
+  const {
+    token,
+    fromChain,
+    sender,
+    recipient,
+    amount,
+    feeBps,
+    feeRecipient,
+    skipFee,
+  } = params;
+
+  if (amount <= 0n) throw new Error("amount must be > 0");
+
+  const split = skipFee
+    ? { feeAmount: 0n, bridgeAmount: amount, feeBps: 0 }
+    : calculateBridgeFee(amount, feeBps);
+
+  if (split.bridgeAmount <= 0n) {
+    throw new Error("bridge amount after fee is zero — increase amount or lower feeBps");
+  }
+
+  const recipientForFee = feeRecipient ?? getBridgeFeeRecipient();
+  const feeIxs = makeBridgeFeeIxs({
+    token,
+    fromChain,
+    sender,
+    feeRecipient: recipientForFee,
+    feeAmount: split.feeAmount,
+  });
+
+  const uniqueMessageKeypair = Keypair.generate();
+  const transferIx = makeTransferRemoteIx({
+    token,
+    fromChain,
+    sender,
+    recipient,
+    amount: split.bridgeAmount,
+    uniqueMessageKeypair,
+  });
+
+  return {
+    instructions: [...feeIxs, transferIx],
+    uniqueMessageKeypair,
+    feeAmount: split.feeAmount,
+    bridgeAmount: split.bridgeAmount,
+  };
+}
+
+// ─── Send + confirm ───────────────────────────────────────────────
+
+/**
+ * Build, sign, and send a bridge transfer in one call.
+ * `wallet` is the sender keypair on the source chain and pays fees + signs.
+ *
+ * `connection` must point to the SOURCE chain RPC:
+ *   - fromChain: "solana" → Solana mainnet RPC
+ *   - fromChain: "nara"   → Nara mainnet RPC
+ */
+export async function bridgeTransfer(
+  connection: Connection,
+  wallet: Keypair,
+  params: Omit<BridgeTransferParams, "sender">,
+  opts?: { skipPreflight?: boolean; computeUnitLimit?: number; computeUnitPrice?: number | "auto" }
+): Promise<BridgeTransferResult> {
+  const built = makeBridgeIxs({
+    ...params,
+    sender: wallet.publicKey,
+  });
+
+  const signature = await sendTx(
+    connection,
+    wallet,
+    built.instructions,
+    [built.uniqueMessageKeypair],
+    {
+      computeUnitLimit: opts?.computeUnitLimit ?? 1_400_000,
+      computeUnitPrice: opts?.computeUnitPrice,
+      skipPreflight: opts?.skipPreflight,
+    }
+  );
+
+  // Try to extract message_id from logs
+  const messageId = await extractMessageId(connection, signature);
+
+  return {
+    signature,
+    messageId,
+    feeAmount: built.feeAmount,
+    bridgeAmount: built.bridgeAmount,
+  };
+}
+
+// ─── Message ID extraction ────────────────────────────────────────
+
+/**
+ * Extract the cross-chain message_id from a dispatch tx's logs.
+ * Returns null if the log is missing (tx not yet visible to RPC, etc.).
+ */
+export async function extractMessageId(
+  connection: Connection,
+  signature: string
+): Promise<string | null> {
+  const tx = await connection.getTransaction(signature, {
+    maxSupportedTransactionVersion: 0,
+    commitment: "confirmed",
+  });
+  if (!tx?.meta?.logMessages) return null;
+  for (const log of tx.meta.logMessages) {
+    const m = log.match(/Dispatched message to \d+, ID (0x[0-9a-fA-F]+)/);
+    if (m && m[1]) return m[1];
+  }
+  return null;
+}
+
+// ─── Message delivery status ──────────────────────────────────────
+
+export interface MessageStatus {
+  /** Whether the message has been processed on the destination chain */
+  delivered: boolean;
+  /** Destination chain tx signature (null if not yet delivered) */
+  deliverySignature: string | null;
+}
+
+/**
+ * Query whether a cross-chain message has been delivered on the destination chain.
+ *
+ * Scans recent transactions on the destination Mailbox for the message_id.
+ * The Hyperlane inbox emits: "Hyperlane inbox processed message 0x..."
+ *
+ * @param destConnection - connection to the DESTINATION chain RPC
+ * @param messageId      - the 0x-prefixed message ID from extractMessageId()
+ * @param toChain        - "solana" | "nara" (which chain to check)
+ * @param opts.limit     - how many recent Mailbox txs to scan (default 50)
+ */
+export async function queryMessageStatus(
+  destConnection: Connection,
+  messageId: string,
+  toChain: BridgeChain,
+  opts?: { limit?: number }
+): Promise<MessageStatus> {
+  const mailbox = mailboxFor(toChain);
+  const limit = opts?.limit ?? 50;
+
+  const sigs = await destConnection.getSignaturesForAddress(mailbox, {
+    limit,
+  });
+
+  for (const entry of sigs) {
+    if (entry.err) continue;
+    const tx = await destConnection.getTransaction(entry.signature, {
+      maxSupportedTransactionVersion: 0,
+      commitment: "confirmed",
+    });
+    if (!tx?.meta?.logMessages) continue;
+    for (const log of tx.meta.logMessages) {
+      if (log.includes(messageId)) {
+        return { delivered: true, deliverySignature: entry.signature };
+      }
+    }
+  }
+
+  return { delivered: false, deliverySignature: null };
+}
+
+// ─── Validator signature status (S3) ──────────────────────────────
+
+const S3_BASE = "https://nara-hyperlane.s3.us-west-1.amazonaws.com";
+
+/** Validator S3 prefixes per source chain */
+const VALIDATOR_PREFIXES: Record<BridgeChain, string[]> = {
+  solana: ["validator-solana-1", "validator-solana-2", "validator-solana-3"],
+  nara: ["validator-nara-1", "validator-nara-2", "validator-nara-3"],
+};
+
+export interface ValidatorSignature {
+  folder: string;
+  signed: boolean;
+  latestIndex: number;
+  serializedSignature: string | null;
+}
+
+export interface MessageSignatureStatus {
+  messageId: string;
+  /** Merkle tree checkpoint index for this message (null if not found) */
+  checkpointIndex: number | null;
+  sourceChain: BridgeChain;
+  validators: ValidatorSignature[];
+  signedCount: number;
+  totalValidators: number;
+  /** All validators have signed */
+  fullySigned: boolean;
+}
+
+async function s3Json<T = unknown>(key: string): Promise<T | null> {
+  try {
+    const resp = await fetch(`${S3_BASE}/${key}`);
+    if (!resp.ok) return null;
+    return (await resp.json()) as T;
+  } catch {
+    return null;
+  }
+}
+
+interface S3Checkpoint {
+  value: {
+    checkpoint: {
+      merkle_tree_hook_address: string;
+      mailbox_domain: number;
+      root: string;
+      index: number;
+    };
+    message_id: string;
+  };
+  signature: { r: string; s: string; v: number };
+  serialized_signature: string;
+}
+
+/**
+ * Query Hyperlane validator signatures for a cross-chain message from AWS S3.
+ *
+ * Each validator stores signed merkle checkpoints in S3. Each checkpoint
+ * at index N contains the message_id of the Nth dispatched message and the
+ * validator's ECDSA signature over the merkle root.
+ *
+ * All validators are scanned concurrently (one goroutine per validator).
+ *
+ * @param messageId   - 0x-prefixed message ID from extractMessageId()
+ * @param sourceChain - source chain where the message was dispatched
+ * @param opts.maxScan - how many checkpoints to scan backwards (default 200)
+ */
+export async function queryMessageSignatures(
+  messageId: string,
+  sourceChain: BridgeChain,
+  opts?: { maxScan?: number }
+): Promise<MessageSignatureStatus> {
+  const prefixes = VALIDATOR_PREFIXES[sourceChain];
+  const maxScan = opts?.maxScan ?? 200;
+
+  // Each validator independently: fetch latest index → reverse-scan for messageId
+  const results = await Promise.all(
+    prefixes.map((folder) => scanValidator(folder, messageId, maxScan))
+  );
+
+  // checkpointIndex comes from whichever validator found it
+  const found = results.find((r) => r.checkpointIndex !== null);
+  const checkpointIndex = found?.checkpointIndex ?? null;
+
+  const validators: ValidatorSignature[] = results.map((r) => ({
+    folder: r.folder,
+    signed: r.signed,
+    latestIndex: r.latestIndex,
+    serializedSignature: r.serializedSignature,
+  }));
+
+  const signedCount = validators.filter((v) => v.signed).length;
+  return {
+    messageId,
+    checkpointIndex,
+    sourceChain,
+    validators,
+    signedCount,
+    totalValidators: prefixes.length,
+    fullySigned: signedCount === prefixes.length,
+  };
+}
+
+async function scanValidator(
+  folder: string,
+  messageId: string,
+  maxScan: number
+): Promise<ValidatorSignature & { checkpointIndex: number | null }> {
+  const latestIndex = await s3Json<number>(
+    `${folder}/checkpoint_latest_index.json`
+  );
+  if (latestIndex === null) {
+    return {
+      folder,
+      signed: false,
+      latestIndex: -1,
+      serializedSignature: null,
+      checkpointIndex: null,
+    };
+  }
+
+  const minIndex = Math.max(0, latestIndex - maxScan);
+  for (let i = latestIndex; i >= minIndex; i--) {
+    const cp = await s3Json<S3Checkpoint>(
+      `${folder}/checkpoint_${i}_with_id.json`
+    );
+    if (cp?.value?.message_id === messageId) {
+      return {
+        folder,
+        signed: true,
+        latestIndex,
+        serializedSignature: cp.serialized_signature,
+        checkpointIndex: i,
+      };
+    }
+  }
+
+  return {
+    folder,
+    signed: false,
+    latestIndex,
+    serializedSignature: null,
+    checkpointIndex: null,
+  };
+}

package/src/constants.ts

@@ -45,3 +45,23 @@ export const DEFAULT_AGENT_REGISTRY_PROGRAM_ID =
  * When empty, uses legacy transactions.
  */
 export const DEFAULT_ALT_ADDRESS = process.env.ALT_ADDRESS || "3uw7RatGTB4hdHnuVLXjsqcMZ87zXsMSc3XbyoPA8mB7";
+
+/**
+ * Bridge fee in basis points (1 bps = 0.01%). 50 = 0.5%.
+ * Deducted from the bridged amount and transferred to DEFAULT_BRIDGE_FEE_RECIPIENT
+ * in the same transaction.
+ */
+export const DEFAULT_BRIDGE_FEE_BPS = 50;
+
+/** BPS denominator (10000 = 100%) */
+export const BRIDGE_FEE_BPS_DENOMINATOR = 10000;
+
+/**
+ * Default fee recipient pubkey for cross-chain bridge transactions.
+ * Same Ed25519 keypair works on both Solana and Nara chains.
+ * Override at runtime via setBridgeFeeRecipient() in src/bridge.ts.
+ *
+ * NOTE: replace with actual fee recipient before mainnet usage.
+ */
+export const DEFAULT_BRIDGE_FEE_RECIPIENT =
+  "FERLFwBpCyoEuvFP68eP6Fv4FCVocnNyyFUCYwpfmjqn";