Guide: Building with On-Chain Escrow

// escrow-gateway-client.mjs -- shared helper, used by every call below
import { createHmac, randomUUID } from 'node:crypto';

const GATEWAY_URL = 'https://api.nhbcoin.com';
const API_KEY = process.env.NHB_ESCROW_API_KEY;
const API_SECRET = process.env.NHB_ESCROW_API_SECRET; // shared HMAC secret

export async function gatewayRequest(method, path, body, walletHeaders = {}) {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const nonce = randomUUID();
  const rawBody = body ? JSON.stringify(body) : '';

  // The Gateway recomputes this exact string server-side and compares --
  // order and the newline separators matter.
  const canonical = [timestamp, nonce, method.toUpperCase(), path, rawBody].join('\n');
  const signature = createHmac('sha256', API_SECRET).update(canonical).digest('hex');

  const res = await fetch(GATEWAY_URL + path, {
    method,
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': API_KEY,
      'X-Timestamp': timestamp,
      'X-Nonce': nonce,
      'X-Signature': signature,
      'Idempotency-Key': randomUUID(),
      ...walletHeaders // X-Sig-Addr / X-Sig -- see Step 2 below
    },
    body: rawBody || undefined
  });

  if (!res.ok) {
    const err = await res.json().catch(() => ({}));
    throw new Error('Gateway ' + path + ' failed (' + res.status + '): ' + (err.error ?? 'unknown error'));
  }
  return res.json();
}

// Create -- signed by the payer. Address fields are raw 20-byte hex here,
// NOT the nhb1... bech32 form used in the request body itself.
{
  "action": "create",
  "payer": "a1b2c3...20 bytes",
  "payee": "d4e5f6...20 bytes",
  "token": "NHB",
  "amount": "100000000000000000000",
  "feeBps": 0,
  "deadline": 1730000000,
  "nonce": 1,
  "mediator": "...omitted entirely if unset",
  "meta": "...omitted entirely if unset",
  "realm": "...omitted entirely if unset"
}

// Release / Refund -- signed by the payee or mediator (release),
// or the payer (refund)
{ "escrowId": "0x...64 hex chars...", "action": "release" }

// Dispute -- signed by either the payer or the payee
{ "escrowId": "0x...64 hex chars...", "action": "dispute", "reason": "item damaged" }

import { ethers } from 'ethers';

// wallet holds the real participant's private key -- never the
// Gateway's relayer key. Run this wherever you control that key:
// your backend, or (for a browser wallet) the customer's own device.
function signEscrowEnvelope(envelope, wallet) {
  // Field order matters -- JSON.stringify on a plain object preserves
  // insertion order, so build 'envelope' in the same order shown above.
  const canonicalJson = JSON.stringify(envelope);
  const digest = ethers.utils.keccak256(ethers.utils.toUtf8Bytes(canonicalJson));

  // Raw digest signing -- NOT wallet.signMessage(), which adds an
  // EIP-191 prefix the Gateway does not expect and will reject.
  const signingKey = new ethers.utils.SigningKey(wallet.privateKey);
  const signature = signingKey.signDigest(digest);
  return ethers.utils.joinSignature(signature); // 0x-prefixed, 65 bytes
}

// The exact bytes the payer signs -- address fields are raw hex here,
// not the nhb1... form used in the request body below.
const createEnvelope = {
  action: 'create',
  payer: payerAddressHex,
  payee: payeeAddressHex,
  token: 'NHB',
  amount: '100000000000000000000', // 100 NHB, 18 decimals
  feeBps: 0,
  deadline: Math.floor(Date.now() / 1000) + 86400, // 24h to fund
  nonce: 1
};
const signature = signEscrowEnvelope(createEnvelope, payerWallet);

const { escrowId, payIntent } = await gatewayRequest(
  'POST',
  '/escrow/create',
  {
    payer: 'nhb1payer...',
    payee: 'nhb1payee...',
    token: 'NHB',
    amount: '100000000000000000000',
    feeBps: 0,
    deadline: createEnvelope.deadline
  },
  { 'X-Sig-Addr': 'nhb1payer...', 'X-Sig': signature }
);
// -> escrowId: '0x...', payIntent: { vault, memo, qr }

// No API key or signature needed -- this is a public, read-only lookup.
const escrow = await fetch(
  'https://api.nhbcoin.com/escrow/' + escrowId
).then((res) => res.json());
// -> { status: 'FUNDED', payer, payee, token, amount, deadline, mediator, events: [...] }

// Payee (or mediator) releases the funds to the payee
const releaseEnvelope = { escrowId, action: 'release' };
const releaseSig = signEscrowEnvelope(releaseEnvelope, payeeWallet);
await gatewayRequest(
  'POST', '/escrow/release', { escrowId },
  { 'X-Sig-Addr': 'nhb1payee...', 'X-Sig': releaseSig }
); // -> 202 { queued: true }

// Payer refunds before release
const refundEnvelope = { escrowId, action: 'refund' };
const refundSig = signEscrowEnvelope(refundEnvelope, payerWallet);
await gatewayRequest(
  'POST', '/escrow/refund', { escrowId },
  { 'X-Sig-Addr': 'nhb1payer...', 'X-Sig': refundSig }
); // -> 202 { queued: true }

// Either side raises a dispute instead
const disputeEnvelope = { escrowId, action: 'dispute', reason: 'item damaged' };
const disputeSig = signEscrowEnvelope(disputeEnvelope, payerWallet);
await gatewayRequest(
  'POST', '/escrow/dispute', { escrowId, reason: 'item damaged' },
  { 'X-Sig-Addr': 'nhb1payer...', 'X-Sig': disputeSig }
); // -> 202 { ok: true }

// POSTed to your configured webhook URL on every state change
{
  "event": "escrow.released",
  "escrowId": "0x...",
  "payer": "nhb1...",
  "payee": "nhb1...",
  "token": "NHB",
  "amount": "100000000000000000000",
  "txHash": "0x...",
  "meta": { "reference": "your-own-order-id" },
  "provider": "nhbchain-escrow-gateway"
}

// Self-hosted: you hold the NHB, you sign, you submit -- no Gateway involved.
// Field encoding here is illustrative -- see the transaction type list
// above and core/types/transaction.go for the exact wire format.
const createEscrowTx = {
  type: 3, // TxTypeCreateEscrow
  nonce: payerAccount.nonce,
  gasLimit: 100000,
  gasPrice: 1,
  data: JSON.stringify({
    payee: payeeAddress,
    token: 'NHB',
    amount: '100000000000000000000',
    feeBps: 0,
    deadline: Math.floor(Date.now() / 1000) + 86400
  })
};
const signedTx = await payerWallet.signTransaction(createEscrowTx);

await fetch('https://api.nhbcoin.com', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'nhb_sendTransaction',
    params: [signedTx],
    id: 1
  })
});