Build on Strait

Hemi tunnels move assets across three chains — Bitcoin, Hemi (an OP-Stack L2), and Ethereum. Strait watches the tunnel contracts on all three and reconstructs each transfer as a single record, tracked from initiation to finality — including Bitcoin-anchored (Proof-of-Proof) finality for BTC routes.

It runs one node per network (mainnet, testnet). Each node is an indexer plus an HTTP API; all state lives in Postgres/Supabase, so the dashboard and any app you build read from the same source of truth.

Every result is a Transfer — the core resource. These are the fields you get (GraphQL camelCase; the REST API returns the same fields in snake_case).

status is what you poll for. Each route has a different sequence of on-chain events before it reaches FINALIZED.

INITIATED ──────────────────────────────────────────► FINALIZED

INITIATED ──────────────────────────────────────────► FINALIZED

INITIATED ──► PROVING ─────────────────────────────► FINALIZED
              (1-day challenge window)

INITIATED ──────────────────────────────────────────► FINALIZED

The node serves on API_HOST:API_PORT (default :8080). Open /graphql in a browser for the interactive GraphiQL playground.

Endpoints

GraphQL queries

# Recent transfers (newest first; limit clamped 1–500, default 50)
{ transfers(limit: 20) { id route asset amount status initiatedAt finalizedAt } }

# A single transfer by id
{ transfer(id: "a2ce3b2d-…") { id route status destChain destTxHash recipient } }

# All transfers for a recipient address (a wallet view)
{ transfersByRecipient(recipient: "0x64ea…951f", limit: 50) { id route amount status } }

# Search by address / tx hash / id, with optional status & route filters
{ searchTransfers(query: "bc1qwql2…", status: "FINALIZED", route: "HEMI_TO_BTC") {
    id amount status finalizedAt } }

# Aggregate stats — optionally scoped to a window
{ stats { totalTransfers finalized failed } }
{ stats(window: LAST_24H) { totalTransfers finalized } }

# Time-bucketed analytics: count + volume per route/asset.
# window: LAST_24H | LAST_7D | LAST_30D | ALL_TIME · granularity: DAY | WEEK | MONTH
# volume is atomic units (sats/wei) per asset — convert client-side.
{ analyticsSeries(window: LAST_30D, granularity: DAY) {
    bucketStart route asset transferCount volume } }

# Which route dominates a window (share is 0–1 of total transfers)
{ routeBreakdown(window: LAST_7D) { route transferCount share } }

Examples

// TypeScript — search via GraphQL
const res = await fetch("http://localhost:8080/graphql", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    query: `query($r:String!){ transfersByRecipient(recipient:$r){ id route status } }`,
    variables: { r: recipient },
  }),
});
const { data } = await res.json();

# curl — REST
curl 'http://localhost:8080/transfers?limit=20'
curl 'http://localhost:8080/transfers/a2ce3b2d-7110-520c-8999-d21d1f88d1e5'

Push notifications for transfer lifecycle events: register a URL and Strait POSTs an HMAC-signed JSON payload to it whenever a matching transfer changes. Deliveries are backed by a durable outbox — a node restart never drops one — and failed POSTs retry with exponential backoff (10s → 24h, 8 attempts). Delivery is at-least-once: dedupe on the X-Strait-Delivery header.

Registering

curl -X POST http://localhost:8080/webhooks \
  -H 'content-type: application/json' \
  -d '{
    "url": "https://example.com/strait-hook",
    "routes":   ["HEMI_TO_BTC", "HEMI_TO_ETH"],
    "assets":   ["BTC", "ETH"],
    "statuses": ["FINALIZED", "FAILED"]
  }'

Filters are optional — omit a dimension to match everything on it. The URL must be public http(s); loopback and private-network hosts are rejected.

Deliveries

The body is { "event", "timestamp", "transfer": { … } } where transfer has the same snake_case shape as GET /transfers rows. Respond with any 2xx within 10 seconds to acknowledge — anything else (or a timeout) schedules a retry.

Verifying signatures

Always verify before trusting a payload — anyone who discovers your endpoint URL can POST fake events to it; only Strait knows your signing_secret. Verify over the raw request bytes: re-serializing parsed JSON can reorder keys and break the digest.

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody /* Buffer */, signatureHeader, secret) {
  const expected =
    "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  return timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
}

What those two calls do (node:crypto ships with Node — no npm package): createHmac recomputes the HMAC-SHA256 signature Strait attached — only a holder of your signing_secret can produce it, and changing one byte of the body changes it completely, so a match proves the payload is genuinely from Strait and untampered. timingSafeEqual compares the signatures in constant time: a plain === returns faster the earlier the first mismatch is, and that timing difference — measured over many forged requests — can leak a valid signature byte by byte. Constant-time comparison closes that side channel.

Credentials & subscriptions

One subscription per service, not per end-user. Strait doesn't know about your users — it notifies you about transfers. A wallet with 10,000 users runs one subscription (per environment) pointed at its backend; when a delivery arrives, match transfer.recipient (or sender) against your own users table to decide who to notify.

Register separately for staging and production, each with its own URL and secrets. To rotate, register a new subscription, accept both secrets during the cutover, then delete the old one. The API never re-discloses secrets — if you lose the management token, keep returning 2xx(and ignore the events) so retries don't pile up, and ask the operator to remove the row.

Integrating with your backend

Two rules for every receiver: verify the signature over the raw request bytes (parse JSON only after the check — body-parsing middleware that re-serializes breaks the digest), and acknowledge fast — return 2xx, then do your real work asynchronously. A handler slower than 10s looks like a failure and gets retried, which you'll then process twice.

Express:

import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const app = express();
const SECRET = process.env.STRAIT_SIGNING_SECRET;

// express.raw (NOT express.json) so we verify the exact bytes.
app.post("/strait-hook", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.get("X-Strait-Signature") ?? "";
  const expected = "sha256=" + createHmac("sha256", SECRET).update(req.body).digest("hex");
  if (sig.length !== expected.length ||
      !timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).send("bad signature");
  }

  res.status(200).send("ok"); // ack first — work after

  const deliveryId = req.get("X-Strait-Delivery"); // your dedupe key
  const { event, transfer } = JSON.parse(req.body);
  if (event === "transfer.status_changed" && transfer.status === "FINALIZED") {
    // mark the user's bridge complete, send a push notification…
  }
});

Next.js (App Router route handler):

// app/api/strait-hook/route.ts
import { createHmac, timingSafeEqual } from "node:crypto";

export async function POST(req: Request) {
  const raw = Buffer.from(await req.arrayBuffer()); // raw bytes, not req.json()
  const sig = req.headers.get("x-strait-signature") ?? "";
  const expected = "sha256=" +
    createHmac("sha256", process.env.STRAIT_SIGNING_SECRET!).update(raw).digest("hex");
  if (sig.length !== expected.length ||
      !timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return new Response("bad signature", { status: 401 });
  }

  const deliveryId = req.headers.get("x-strait-delivery"); // your dedupe key
  const { event, transfer } = JSON.parse(raw.toString());
  // handle the event (keep it quick, or hand off to a queue)…
  return new Response("ok");
}

Recommended pattern — webhook + poll reconciliation. On submit, store a pending row in your DB keyed by the source tx hash. On webhook, match transfer.source_tx_hash to that row, update it, notify the user. Then reconcile: webhooks are at-least-once, but if your endpoint is down longer than the retry window (~1.5 days) a delivery can permanently fail — so sweep your still-pending rows every ~10 minutes and resolve them by polling:

async function fetchByTxHash(txHash) {
  const res = await fetch("http://localhost:8080/graphql", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      query: `query($q: String) {
        searchTransfers(query: $q, limit: 1) {
          id status route asset amount destTxHash finalizedAt
        }
      }`,
      variables: { q: txHash },
    }),
  });
  const { data } = await res.json();
  return data?.searchTransfers?.[0] ?? null;
}

The webhook gives you low latency; the sweep guarantees you never miss a terminal state. Both read the same records, so they can share handling code.

Managing a subscription

The Webhooks page does all of this in the browser — register, inspect delivery history, delete. The same operations over curl:

# Inspect (metadata only — secrets are never returned)
curl http://localhost:8080/webhooks/<id> -H 'X-Management-Token: <token>'

# Last 20 delivery attempts: event, status, attempt count, response time, error
curl http://localhost:8080/webhooks/<id>/deliveries -H 'X-Management-Token: <token>'

# Unsubscribe (pending deliveries are removed with it)
curl -X DELETE http://localhost:8080/webhooks/<id> -H 'X-Management-Token: <token>'

Strait watches these tunnel contracts. ETH/ERC-20 routes flow through the OP-Stack StandardBridge; BTC routes through the BitcoinTunnelManager, with Bitcoin state read via the BitcoinKit precompile on Hemi (no separate Bitcoin node required).