DEV Community: Jayden Cristian

Why "just retry it" can be dangerous

Jayden Cristian — Wed, 04 Nov 2026 19:38:04 +0000

Your Node.js service calls an external API. The request times out, returns 503 Service Unavailable, or gets a 429 Too Many Requests response. A retry sounds reasonable: wait briefly, send the same request again, and continue.

But not every failed-looking request actually failed on the server.

A timeout means the client did not receive the expected result in time. The server might have completed the operation and lost the response on the way back. If the request created a payout, order, or exchange operation, a blind retry could create it twice.

The practical goal isn't to retry everything. It's to retry only when the operation is safe, with a clear limit and a delay that respects the server.

We'll build a small JSON HTTP client using built-in Node.js APIs, then test transient errors, backoff, Retry-After, timeouts, and duplicate-request safety.

Scope: This is a standalone educational example, not the internal infrastructure of any cryptocurrency platform. It uses Node.js 22-compatible APIs, supports GET and explicitly opted-in POST, and expects a JSON response body on success. It is not a production-ready transaction client.

First, classify the failure

These cases require different decisions:

What happened	Suggested behavior in this example
Network failure or request timeout	Retry an eligible operation, within a bounded attempt limit
`429 Too Many Requests`	Respect `Retry-After` when provided; otherwise use backoff
`503 Service Unavailable`, `502`, `504`	Consider a bounded retry for eligible operations
`408 Request Timeout` or selected `500` errors	Retry only according to a deliberate policy
`400`, `401`, `403`, `404`	Do not automatically retry without a change or an explicit contract
`POST` with an unknown result	Do not retry blindly; confirm idempotency support or reconcile the operation

fetch() doesn't reject just because a server responds with HTTP 503. You still need to inspect response.status. Network errors and aborts, on the other hand, reject the promise.

1. Put a timeout on each attempt

Modern Node.js has fetch() and AbortSignal.timeout() built in:

const response = await fetch('https://api.example.test/data', {
  signal: AbortSignal.timeout(3000),
});

The URL above is deliberately a placeholder. Replace it with a real endpoint that you control or are authorized to query.

With a timeout signal, a request is aborted after the configured interval. Crucially, aborting the client-side request does not undo a remote operation that the server may already have started or completed.

Also distinguish two kinds of cancellation:

Per-attempt timeout: One attempt took too long. An eligible read can be retried.
Caller cancellation: The user, job, or parent request no longer needs the result. Stop the entire retry loop.

AbortSignal.any() combines the two signals. Our client will also read the JSON response inside the attempt's timeout window, instead of returning a Response and parsing its body later.

2. Add exponential backoff with jitter

Retrying immediately after a failure can make an overloaded service even slower. A simple exponential backoff increases the potential delay between attempts:

Attempt 1 fails → max backoff 300 ms
Attempt 2 fails → max backoff 600 ms
Attempt 3 fails → max backoff 1,200 ms
Attempt 4       → no retry after final failure

These are delay caps, not the exact sleeps. We'll use full jitter: choose a random delay between zero and the current capped value. That spreads clients out, helping avoid a synchronized retry spike.

The policy is bounded: four total attempts means one initial request plus at most three retries—not four retries.

3. Respect Retry-After without retrying too early

For 429 and 503, servers may include Retry-After:

HTTP/1.1 429 Too Many Requests
Retry-After: 5

That means wait five seconds before another attempt. The header can also be an HTTP date.

Our implementation has a maximum amount of time it is willing to wait. If the server asks for an hour but the operation has only a ten-second wait budget, the client stops. It must not quietly truncate the server's required delay and retry too early. A higher-level job scheduler may choose to resume later.

4. Build a reusable JSON retry client

Create retry-json.mjs:

import { setTimeout as delay } from 'node:timers/promises';

const RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
const defaultWait = (ms, signal) => delay(ms, undefined, { signal });

export function parseRetryAfter(value, now = Date.now()) {
  if (value == null) return null;
  const text = value.trim();
  if (/^\d+$/.test(text)) {
    const seconds = Number(text);
    return Number.isSafeInteger(seconds) && seconds <= Number.MAX_SAFE_INTEGER / 1000
      ? seconds * 1000 : Infinity;
  }
  // The commonly used IMF-fixdate HTTP-date format, e.g. Fri, 23 Oct 2026 12:00:03 GMT.
  if (!/^[A-Za-z]{3}, \d{2} [A-Za-z]{3} \d{4} \d{2}:\d{2}:\d{2} GMT$/.test(text)) {
    return null;
  }
  const timestamp = Date.parse(text);
  return Number.isNaN(timestamp) ? null : Math.max(0, timestamp - now);
}

export async function fetchJsonWithRetry(url, {
  method = 'GET',
  headers = {},
  body,
  maxAttempts = 4,
  requestTimeoutMs = 3000,
  baseDelayMs = 300,
  maxBackoffMs = 3000,
  maxRetryAfterMs = 10_000,
  allowPostRetry = false,
  idempotencyKey,
  signal,
  fetchImpl = fetch,
  wait = defaultWait,
  random = Math.random,
  now = Date.now,
} = {}) {
  const httpMethod = method.toUpperCase();
  if (!['GET', 'POST'].includes(httpMethod)) {
    throw new TypeError('This JSON example supports GET and POST only');
  }
  if (!Number.isInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > 8 ||
      !Number.isSafeInteger(requestTimeoutMs) || requestTimeoutMs < 1 ||
      !Number.isSafeInteger(baseDelayMs) || baseDelayMs < 1 ||
      !Number.isSafeInteger(maxBackoffMs) || maxBackoffMs < baseDelayMs ||
      !Number.isSafeInteger(maxRetryAfterMs) || maxRetryAfterMs < 0) {
    throw new RangeError('Invalid retry configuration');
  }
  if (httpMethod === 'POST' && allowPostRetry &&
      (typeof idempotencyKey !== 'string' || !idempotencyKey.trim() || typeof body !== 'string')) {
    throw new TypeError('Retrying POST requires a stable key and repeatable string body');
  }

  // POST retries are an explicit opt-in; the remote API must guarantee deduplication.
  const canRetry = httpMethod === 'GET' || (httpMethod === 'POST' && allowPostRetry);
  const requestHeaders = new Headers(headers);
  if (idempotencyKey != null) requestHeaders.set('Idempotency-Key', idempotencyKey);

  const jitter = (attempt) => {
    const cap = Math.min(maxBackoffMs, baseDelayMs * 2 ** (attempt - 1));
    return Math.floor(random() * (cap + 1)); // Full jitter in [0, cap].
  };

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    signal?.throwIfAborted();
    const timeoutSignal = AbortSignal.timeout(requestTimeoutMs);
    const attemptSignal = signal
      ? AbortSignal.any([signal, timeoutSignal])
      : timeoutSignal;
    let response;

    try {
      response = await fetchImpl(url, {
        method: httpMethod,
        headers: requestHeaders,
        body,
        signal: attemptSignal,
      });
    } catch (error) {
      if (signal?.aborted) throw signal.reason;
      const transient = error instanceof TypeError || timeoutSignal.aborted;
      if (!canRetry || attempt === maxAttempts || !transient) throw error;
      await wait(jitter(attempt), signal);
      continue;
    }

    if (response.ok) {
      try {
        // Read within the timeout window, not after returning the Response.
        return await response.json();
      } catch (error) {
        if (signal?.aborted) throw signal.reason;
        if (!canRetry || attempt === maxAttempts || !timeoutSignal.aborted) throw error;
        await wait(jitter(attempt), signal);
        continue;
      }
    }

    const status = response.status;
    const header = response.headers.get('Retry-After');
    // Release the body before retrying to avoid holding connections unnecessarily.
    if (response.body) {
      try { await response.body.cancel(); } catch { /* already closed */ }
    }
    if (!canRetry || !RETRYABLE_STATUSES.has(status) || attempt === maxAttempts) {
      throw new Error(`HTTP ${status}`);
    }
    const serverWaitMs = parseRetryAfter(header, now());
    if (serverWaitMs !== null && serverWaitMs > maxRetryAfterMs) {
      // Do not silently cap Retry-After and hit the server too early.
      throw new Error(`Retry-After exceeds local wait budget (HTTP ${status})`);
    }
    await wait(serverWaitMs ?? jitter(attempt), signal);
  }
}

A few choices are intentional:

The helper only retries GET by default. It supports POST, but does not retry it unless the caller explicitly opts in and supplies a stable idempotency key and reusable string body.
The server—not the header alone—must actually implement idempotency semantics for that endpoint. Sending an arbitrary Idempotency-Key to an API that ignores it provides no protection.
The sample treats 408, 429, 500, 502, 503, and 504 as retryable HTTP statuses only for requests eligible for retry. This is an illustrative policy, not a universal rule for every API.
Invalid JSON is not treated as a transient network problem. The request succeeded at the HTTP level but its response is not valid for this JSON client.
The example accepts standard Retry-After seconds and the common IMF-fixdate HTTP-date format. Other historical date formats are outside its scope.

5. Use it for a read-only API request

import { fetchJsonWithRetry } from './retry-json.mjs';

// Replace this placeholder with your own JSON GET endpoint.
const data = await fetchJsonWithRetry('https://api.example.test/rates', {
  maxAttempts: 4,
  requestTimeoutMs: 3000,
  baseDelayMs: 300,
  maxBackoffMs: 3000,
});

console.log(data);

This is a usage illustration. The .test file below uses mock responses instead of making real HTTP requests, so you can reproduce the results without an API key or an internet connection.

6. What about POST and duplicate operations?

HTTP defines GET as safe and idempotent, assuming the server implements the method correctly. A POST may create a new resource or trigger a financial side effect; repeating it can repeat the side effect.

Imagine creating a payout operation:

Your client sends POST /payouts.
The server creates the payout.
The response gets lost, and your client times out.
A naive retry sends another POST /payouts.

There could now be two payouts. A client-side timeout is not proof that the first payout failed.

Some APIs explicitly support a stable idempotency key for operations like this. If—and only if—the provider documents and guarantees that contract for the endpoint, you may opt in:

import { fetchJsonWithRetry } from './retry-json.mjs';

// ILLUSTRATIVE ONLY: the target endpoint must document idempotency support.
const payload = JSON.stringify({
  amount: '100.00',
  currency: 'USD',
});

const operation = await fetchJsonWithRetry('https://api.example.test/payouts', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: payload,
  allowPostRetry: true,
  idempotencyKey: 'payout-workflow-123',
});

The same key and the exact same payload are sent on every attempt. In real systems, persist the key before calling the provider, bind it to the logical business operation, and keep it stable across process restarts. The provider must reject conflicting payloads under the same key and implement its own deduplication; key retention periods and response-replay behavior depend on that provider's contract.

If you cannot verify the remote operation's outcome or the provider's idempotency semantics, reconcile before retrying. That may mean querying the operation by your stable reference or escalating the uncertain result to a reconciliation worker.

7. Test the retry policy without external requests

The helper allows fetch, waiting, and randomness to be injected. This lets us simulate different failures quickly and deterministically.

Create retry-json.test.mjs. Here is a focused set of runnable tests:

import test from 'node:test';
import assert from 'node:assert/strict';
import { fetchJsonWithRetry } from './retry-json.mjs';

const url = 'https://api.example.test/data';
const reply = (status, data = {}, headers = {}) =>
  new Response(JSON.stringify(data), { status, headers });

test('GET retries 503 twice, then succeeds', async () => {
  const steps = [reply(503), reply(503), reply(200, { ok: true })];
  const waits = [];
  const result = await fetchJsonWithRetry(url, {
    fetchImpl: async () => steps.shift(),
    baseDelayMs: 100,
    random: () => 0.5,
    wait: async (ms) => waits.push(ms),
  });
  assert.deepEqual(result, { ok: true });
  assert.deepEqual(waits, [50, 100]);
});

test('429 honors Retry-After', async () => {
  const steps = [reply(429, {}, { 'Retry-After': '2' }), reply(200)];
  const waits = [];
  await fetchJsonWithRetry(url, {
    fetchImpl: async () => steps.shift(),
    wait: async (ms) => waits.push(ms),
  });
  assert.deepEqual(waits, [2000]);
});

test('does not retry a POST by default', async () => {
  let calls = 0;
  await assert.rejects(fetchJsonWithRetry(url, {
    method: 'POST',
    body: '{"amount":"100"}',
    fetchImpl: async () => { calls++; return reply(503); },
  }), /HTTP 503/);
  assert.equal(calls, 1);
});

test('opted-in POST reuses its idempotency key', async () => {
  const headersSeen = [];
  const result = await fetchJsonWithRetry(url, {
    method: 'POST',
    body: '{"amount":"100"}',
    allowPostRetry: true,
    idempotencyKey: 'operation-123',
    fetchImpl: async (_, options) => {
      headersSeen.push(options.headers.get('Idempotency-Key'));
      return headersSeen.length === 1 ? reply(503) : reply(200, { ok: true });
    },
    wait: async () => {},
  });
  assert.deepEqual(result, { ok: true });
  assert.deepEqual(headersSeen, ['operation-123', 'operation-123']);
});

Run them with Node.js 22 or another compatible current version:

node --test retry-json.test.mjs

An extended local test suite of 16 cases also checks timeouts, caller cancellation, invalid JSON, excessive Retry-After values, HTTP dates, validation, and retry exhaustion. All 16 passed on Node.js 22.16.0. These are mock-based tests, not performance benchmarks or tests against a real payment provider.

8. Production concerns beyond this demo

A short retry helper is only one layer of resilience. Before adopting a policy in a production backend, consider:

End-to-end deadline: The demo limits each attempt and each Retry-After wait, but does not impose one explicit absolute deadline for the whole operation. A total deadline, queue deadline, or request budget is often needed.
Retry amplification: If a frontend, API gateway, job worker, and provider SDK all retry independently, one failure can multiply into many requests. Choose where retries belong.
Idempotency and persistence: A stable key should be persisted and associated with the intended operation. Your own database may also need unique constraints, event deduplication, and transactional outbox processing.
Rate limiting: Retry-After helps, but real clients may also need shared rate limits, concurrency limits, and circuit breakers.
Observability: Record the operation ID, attempt number, HTTP status, elapsed time, and final outcome. Avoid logging access tokens, request secrets, or sensitive payloads.
Ambiguous outcomes: A timed-out write should enter a reconciliation path when the remote result is unknown. Do not turn uncertainty into an automatic second payment.
Replayable bodies: The example permits retries only for POST requests with a reusable string body. Streams and other one-shot bodies need different handling.

Key takeaways

Reliable retries require more than a for loop:

Timeout each attempt, and recognize that a timeout says nothing definitive about remote side effects.
Retry only eligible operations and carefully selected transient failures.
Back off with jitter, and honor the server's Retry-After instructions.
Bound the total number of attempts and stop when the server's requested delay exceeds your wait budget.
Never assume an idempotency key works unless the provider explicitly implements it for that endpoint.
Reconcile uncertain writes rather than blindly repeating them.

These practices won't eliminate network failures. They make your Node.js service less likely to turn a temporary problem into extra load, duplicate operations, or incorrect financial state.

References

AI disclosure: This initial draft and code examples were generated with AI assistance. The runnable example was tested with Node.js 22.16.0 using mock responses. Human technical review is required before publication.

Modeling Blockchain Deposit Workflows with a State Machine in Node.js

Jayden Cristian — Fri, 30 Oct 2026 17:51:24 +0000

The duplicate delivery problem

Imagine a Node.js worker processing a blockchain deposit confirmation. It receives an event, updates a swap to exchange, and schedules the next operation.

The worker commits the update—but crashes before acknowledging the message. The queue delivers the event again. Another observer might even publish a new event ID for the same deposit confirmation.

If the handler simply performs an update and queues another job on every delivery, one deposit can trigger multiple exchange operations.

This is why idempotency matters: processing the same logical action more than once should not create additional business effects.

In this tutorial, we'll model two separate protections:

Event deduplication: recognize a delivery that has already been recorded.
Business idempotency: recognize that a workflow has already performed the requested transition, even when a new event ID is used.

We'll add a transactional outbox so the state change and the intention to perform the next operation are committed together.

Scope: This is a standalone educational example, not CryptoDeepApp's production architecture. A dependency-free in-memory model lets us test the behavior; a separate MongoDB adapter illustrates durable multi-document transactions. We do not connect to blockchain nodes or send real funds. Confirmation events are assumed to come from a trusted verifier that already checked the chain, destination, asset, amount, and confirmation/finality policy.

Two identities, two different jobs

A delivery ID and a business-operation ID are not interchangeable.

Identifier	Example	Purpose
Event ID	`chain-watcher:event-001`	Detect replay of the same delivered event
Deposit reference	`btc-mainnet:tx-abc:vout-0`	Identify the specific on-chain transfer
Workflow ID	`swap-42`	Identify the business process being updated
Outbox operation ID	`start-exchange:swap-42`	Prevent scheduling the same logical next operation twice

A transaction hash alone may be insufficient to identify a deposit. Bitcoin transactions can have multiple outputs; other chains may require a log or instruction index. The example treats depositRef as a prevalidated, chain-specific identifier.

Consider this already-observed deposit:

const workflow = {
  id: 'swap-42',
  status: 'deposit',
  depositRef: 'btc-mainnet:tx-abc:vout-0',
  amountUnits: '12500000', // Integer base units, never a floating-point amount.
  revision: 3,
};

const event = {
  eventId: 'chain-watcher:event-001',
  workflowId: 'swap-42',
  type: 'DEPOSIT_CONFIRMED',
  depositRef: 'btc-mainnet:tx-abc:vout-0',
  amountUnits: '12500000',
};

The workflow has already reached deposit: funds were observed, but the application's confirmation policy was not yet satisfied. A verified DEPOSIT_CONFIRMED event may move it to exchange.

We deliberately do not allow that event to jump from waiting or overdue straight to exchange. If a late deposit appears, its observation and any required review belong to a separate step.

Why a processed-events check alone is not enough

This code has a race condition:

// Unsafe pseudocode — don't use it as an idempotency guarantee.
if (!(await processedEvents.findOne({ eventId }))) {
  await updateTransaction();
  await processedEvents.insertOne({ eventId });
}

Two workers can both read "not processed" before either inserts anything. And if the first update succeeds but the process crashes before inserting the receipt, the next delivery repeats the update.

A durable design needs database-enforced uniqueness and an atomic relationship between receiving an event, changing the workflow, and recording the next action.

Build a testable model in plain Node.js

First, we'll make the behavior easy to test without MongoDB. Create idempotent-events.mjs:

// Educational in-memory implementation; NOT durable or distributed.
export function validateEvent(event) {
  if (!event || typeof event !== 'object' || event.type !== 'DEPOSIT_CONFIRMED') {
    throw new TypeError('Expected a DEPOSIT_CONFIRMED event');
  }
  for (const field of ['eventId', 'workflowId', 'depositRef']) {
    if (typeof event[field] !== 'string' || !event[field].trim()) {
      throw new TypeError(`${field} must be a non-empty string`);
    }
  }
  if (typeof event.amountUnits !== 'string' || !/^[1-9]\d*$/.test(event.amountUnits)) {
    throw new TypeError('amountUnits must be a positive integer string');
  }
}

export function fingerprint(event) {
  return JSON.stringify([
    event.type, event.workflowId, event.depositRef, event.amountUnits,
  ]);
}

export function planDepositConfirmation(workflow, event) {
  if (!workflow) throw new Error('Unknown workflow; reconcile before acknowledgement');
  if (workflow.depositRef !== event.depositRef ||
      workflow.amountUnits !== event.amountUnits) {
    throw new Error('Deposit identity or amount mismatch; needs reconciliation');
  }
  if (workflow.status === 'deposit') return 'advance';
  if (['exchange', 'sending', 'success'].includes(workflow.status)) {
    return 'already-applied';
  }
  throw new Error(`Cannot confirm deposit from status ${workflow.status}`);
}

export class InMemoryStore {
  #data;
  #tail = Promise.resolve();

  constructor(workflows = []) {
    const keyed = new Map();
    for (const workflow of workflows) {
      if (keyed.has(workflow.id)) throw new Error('Duplicate workflow ID');
      keyed.set(workflow.id, structuredClone(workflow));
    }
    this.#data = { workflows: keyed, inbox: new Map(), outbox: new Map() };
  }

  async transaction(fn) {
    // Serializes calls in THIS Node.js process. Not a real database transaction.
    const previous = this.#tail;
    let unlock;
    this.#tail = new Promise((resolve) => { unlock = resolve; });
    await previous;
    try {
      const draft = structuredClone(this.#data);
      const result = await fn(draft);
      this.#data = draft; // Simulated all-or-nothing commit.
      return result;
    } finally {
      unlock();
    }
  }

  snapshot() {
    return structuredClone(this.#data);
  }
}

export async function processDepositConfirmed(store, event) {
  validateEvent(event);
  const identity = fingerprint(event);

  return store.transaction(async (data) => {
    const previous = data.inbox.get(event.eventId);
    if (previous) {
      if (previous.fingerprint !== identity) {
        throw new Error('Event ID reused with different payload');
      }
      return { outcome: 'duplicate-delivery' };
    }

    const workflow = data.workflows.get(event.workflowId);
    const plan = planDepositConfirmation(workflow, event);
    data.inbox.set(event.eventId, { fingerprint: identity, outcome: plan });

    if (plan === 'already-applied') return { outcome: plan };

    const operationId = `start-exchange:${event.workflowId}`;
    if (data.outbox.has(operationId)) {
      throw new Error('Outbox operation already exists; reconcile conflict');
    }
    data.workflows.set(event.workflowId, {
      ...workflow, status: 'exchange', revision: workflow.revision + 1,
    });
    data.outbox.set(operationId, {
      id: operationId,
      type: 'START_EXCHANGE',
      workflowId: event.workflowId,
      status: 'pending',
    });
    return { outcome: 'applied', operationId };
  });
}

There are three important decisions in this code:

A repeated event ID returns duplicate-delivery. If the same ID appears with different meaningful fields, the handler rejects it rather than silently trusting the new payload.
A different event ID describing a confirmation already reflected by the workflow returns already-applied. This prevents a second business transition.
The workflow state and a uniquely named outbox record are written in the same simulated unit of work. Errors discard the draft instead of leaving half-applied changes.

The model serializes simulated transactions inside one process. It does not provide persistence, cross-process locking, crash recovery, or database isolation. Its purpose is to verify the rules before translating them to real storage.

Test duplicates and concurrent deliveries

Node.js includes a built-in test runner. Create idempotent-events.test.mjs:

import test from 'node:test';
import assert from 'node:assert/strict';
import { InMemoryStore, processDepositConfirmed } from './idempotent-events.mjs';

const workflow = {
  id: 'swap-42', status: 'deposit', revision: 3,
  depositRef: 'btc-mainnet:tx-abc:vout-0', amountUnits: '12500000',
};
const event = {
  eventId: 'chain-watcher:event-001', workflowId: 'swap-42',
  type: 'DEPOSIT_CONFIRMED',
  depositRef: 'btc-mainnet:tx-abc:vout-0', amountUnits: '12500000',
};

test('replayed event does not create another outbox operation', async () => {
  const store = new InMemoryStore([workflow]);
  const first = await processDepositConfirmed(store, event);
  const replay = await processDepositConfirmed(store, event);
  assert.equal(first.outcome, 'applied');
  assert.equal(replay.outcome, 'duplicate-delivery');
  assert.equal(store.snapshot().outbox.size, 1);
});

test('a new event ID cannot repeat the business transition', async () => {
  const store = new InMemoryStore([workflow]);
  await processDepositConfirmed(store, event);
  const second = await processDepositConfirmed(store, {
    ...event, eventId: 'chain-watcher:event-002',
  });
  assert.equal(second.outcome, 'already-applied');
  assert.equal(store.snapshot().workflows.get('swap-42').revision, 4);
});

test('25 concurrent deliveries still schedule one operation', async () => {
  const store = new InMemoryStore([workflow]);
  const results = await Promise.all(Array.from({ length: 25 }, (_, i) =>
    processDepositConfirmed(store, { ...event, eventId: `source:event-${i}` })
  ));
  assert.equal(results.filter(r => r.outcome === 'applied').length, 1);
  assert.equal(store.snapshot().outbox.size, 1);
});

Run:

node --test idempotent-events.test.mjs

The downloadable example includes 19 unit tests. All passed on Node.js 22.16.0. They also cover missing workflows, mismatched deposit references, changed amounts, invalid states, conflicting event IDs, and simulated rollback. These are in-memory behavioral tests—not MongoDB integration tests or throughput benchmarks.

Move the guarantee into MongoDB

For a real multi-worker service, the uniqueness and atomicity must be enforced by a shared durable store.

A possible MongoDB data model is:

workflows
  _id: swap-42
  status: deposit
  revision: 3
  depositRef: btc-mainnet:tx-abc:vout-0
  amountUnits: "12500000"

event_inbox
  _id: chain-watcher:event-001
  fingerprint: [canonical event fields]

event_outbox
  _id: start-exchange:swap-42
  type: START_EXCHANGE
  status: pending

MongoDB provides a unique index on _id by default. That gives us uniqueness for event receipts and outbox operation IDs. A conditional update can additionally check that the workflow still has the expected status and revision.

The official MongoDB Node.js driver supports withSession() and withTransaction() for operations that need to commit across multiple collections. Here is the core pattern, with validateEvent(), fingerprint(), and planDepositConfirmation() imported from the previous example:

export async function processDepositConfirmedMongo(client, db, event) {
  validateEvent(event);
  const fp = fingerprint(event);
  const inbox = db.collection('event_inbox');
  const workflows = db.collection('workflows');
  const outbox = db.collection('event_outbox');

  try {
    return await client.withSession(async (session) =>
      session.withTransaction(async () => {
        await inbox.insertOne({
          _id: event.eventId,
          fingerprint: fp,
          workflowId: event.workflowId,
        }, { session });

        const workflow = await workflows.findOne({ _id: event.workflowId }, { session });
        const plan = planDepositConfirmation(workflow, event);
        if (plan === 'already-applied') return { outcome: plan };

        const result = await workflows.updateOne({
          _id: event.workflowId,
          status: 'deposit',
          revision: workflow.revision,
          depositRef: event.depositRef,
          amountUnits: event.amountUnits,
        }, {
          $set: { status: 'exchange' },
          $inc: { revision: 1 },
        }, { session });
        if (result.modifiedCount !== 1) {
          throw new Error('Concurrent state change; retry or reconcile event');
        }

        const operationId = `start-exchange:${event.workflowId}`;
        await outbox.insertOne({
          _id: operationId,
          type: 'START_EXCHANGE',
          workflowId: event.workflowId,
          status: 'pending',
        }, { session });
        return { outcome: 'applied', operationId };
      }, {
        readConcern: { level: 'snapshot' },
        writeConcern: { w: 'majority' },
      })
    );
  } catch (error) {
    if (error?.code !== 11000) throw error;
    // A unique-outbox collision is NOT necessarily a duplicate event.
    const existing = await inbox.findOne({ _id: event.eventId });
    if (!existing) throw error;
    if (existing.fingerprint !== fp) {
      throw new Error('Event ID reused with different payload');
    }
    return { outcome: 'duplicate-delivery' };
  }
}

This adapter is an architectural illustration; it was not integration-tested against a MongoDB instance. It requires a supported MongoDB deployment for multi-document transactions (typically a replica set or sharded cluster), appropriately provisioned collections, and a compatible official Node.js driver.

The important properties are:

Insert an inbox receipt with a unique event ID.
Validate the existing workflow and perform a compare-and-set update using its status and revision.
Insert a uniquely identified outbox operation in the same transaction.
Commit them together—or roll them all back.

The driver can retry transaction callbacks for certain transient errors. For this reason, do not call an external exchange, send a notification, or transfer funds inside the transaction callback. Such a side effect could run again even if the database work was rolled back and retried.

An outbox record is not an exactly-once payout

The outbox solves a specific failure window:

Database commit succeeds
        ↓
Process crashes before publishing next job

Because the intended next action is already stored in event_outbox, another worker can discover it later.

However, that worker could send a request to an external provider, lose the response, and retry. A unique outbox record prevents the creation of duplicate logical jobs, not necessarily repeated external execution.

A production outbox consumer needs an atomic claim/lease strategy, recovery from expired claims, bounded retries, and a stable operation ID. Whenever possible, the external provider must support an idempotency contract for that ID. Otherwise, the worker needs an explicit reconciliation path before attempting the side effect again.

Do not describe this combination as universal "exactly-once delivery." The realistic goal is at-least-once delivery with idempotent effects where the contracts permit it.

Edge cases worth designing before production

Same event ID, different payload. Treat this as an integrity conflict. A replay must not silently redefine the amount or deposit reference.

Same deposit, different event IDs. The inbox cannot catch this by itself. Your workflow transition and unique business-operation key must prevent another exchange from starting.

Out-of-order events. If a confirmation arrives before the deposit is associated with a workflow, don't pretend the transition is valid. Retry, reconcile, or investigate according to the system's event-ordering guarantees.

Reorganizations and reversals. A confirmation policy is chain-specific. A reorg or revoked upstream event may need a separate compensating workflow; the code here does not implement that.

Multiple valid deposits. Never assume one transaction hash means one transfer. Multiple outputs, transfers, or partial deposits need explicit models and reconciliation rules.

Inbox retention. Deleting old receipts changes what can be recognized as an identical delivery. Plan retention relative to replay windows, and keep independent business-level guards.

Transaction conflicts. A failed conditional update or duplicate outbox ID might be a concurrency conflict, not a safe duplicate. Log it with the relevant IDs and retry or reconcile according to a bounded policy.

Performance. Multi-document transactions and indexes have costs. For simpler problems, an atomic single-document update can be sufficient. Use a transactional outbox when multiple collections must commit together.

Key takeaways

Idempotency is not just an if check in a message handler.

Use event IDs to deduplicate exact deliveries.
Use business identifiers and state guards to prevent repeating the logical operation under a new event ID.
Enforce critical invariants with unique indexes and conditional writes.
Use a transactional outbox when the state update and next-action record must commit atomically.
Assume the worker or provider can retry; exactly-once external effects are not guaranteed without an appropriate downstream contract.
Test duplicate, concurrent, conflicting, and out-of-order inputs—not only the happy path.

A duplicated event should be uneventful. Getting there requires clear identities, explicit state rules, and storage guarantees that survive more than one process.

References

AI disclosure: This educational draft and its sample code were prepared with AI assistance. The in-memory example passed local tests; the MongoDB adapter has not been validated against a live database. Review and adapt the material before publication.

Handling Cryptocurrency Amounts in JavaScript Without Floating-Point Errors

Jayden Cristian — Fri, 23 Oct 2026 17:46:09 +0000

Why a small rounding error matters

Try this in your browser console or Node.js:

console.log(0.1 + 0.2); // 0.30000000000000004

This is expected behavior, not a JavaScript bug. The Number type uses IEEE 754 binary floating-point values, so many decimal fractions cannot be represented exactly.

That usually isn't a problem when you're positioning an element on a page. It becomes a problem when a value represents a cryptocurrency balance, transfer amount, fee, or transaction limit.

For financial amounts, the goal is not to hide floating-point artifacts with formatting. It's to avoid introducing them into the calculation.

Let's build a small JavaScript utility that parses decimal amounts into integer base units, performs exact arithmetic, and formats the results without converting back to Number.

The code below is a standalone educational example, not a description of any particular exchange's production implementation. It handles non-negative amounts and intentionally enforces a limited input format.

Store amounts in the smallest unit

Most crypto assets have a defined number of decimal places. For example:

Asset	Decimal places	Smallest unit example
Bitcoin (BTC)	8	`0.00000001 BTC = 1 satoshi`
Ether (ETH)	18	`0.000000000000000001 ETH = 1 wei`
ERC-20 tokens	Token-specific	Read the token's `decimals` metadata

Instead of storing 0.1 BTC as a floating-point value, store 10,000,000 satoshis as an integer. The decimal separator becomes a concern only when parsing input or displaying output.

The decimal precision is part of the asset definition. Never assume that two tokens—or even versions of an asset on different chains—have the same precision.

Why `BigInt` is useful

JavaScript's Number can represent integers exactly only up to Number.MAX_SAFE_INTEGER (9007199254740991). BigInt supports integer arithmetic without that safe-integer limit.

console.log(Number('9007199254740993'));
// 9007199254740992 — precision has already been lost

console.log(BigInt('9007199254740993'));
// 9007199254740993n — exact

The distinction matters for base-unit quantities, which can grow large even when the human-readable asset amount looks ordinary.

BigInt doesn't store decimal fractions, and that's an advantage here: we convert the decimal string into an integer before doing any arithmetic.

Build two small utilities

Create a file named amounts.mjs:

function validateDecimals(decimals) {
  // Application-level guard for this demonstration.
  if (!Number.isInteger(decimals) || decimals < 0 || decimals > 30) {
    throw new RangeError('decimals must be an integer from 0 to 30');
  }
}

export function parseUnits(value, decimals) {
  validateDecimals(decimals);

  if (typeof value !== 'string' || !/^(0|[1-9]\d*)(?:\.\d+)?$/.test(value)) {
    throw new TypeError('amount must be an unsigned decimal string');
  }

  const [whole, fraction = ''] = value.split('.');
  if (fraction.length > decimals) {
    throw new RangeError(`amount exceeds ${decimals} decimal places`);
  }

  const base = 10n ** BigInt(decimals);
  const fractionalUnits = BigInt(fraction.padEnd(decimals, '0') || '0');
  return BigInt(whole) * base + fractionalUnits;
}

export function formatUnits(units, decimals) {
  validateDecimals(decimals);

  if (typeof units !== 'bigint' || units < 0n) {
    throw new TypeError('units must be a non-negative bigint');
  }

  const base = 10n ** BigInt(decimals);
  const whole = (units / base).toString();
  if (decimals === 0) return whole;

  const fraction = (units % base)
    .toString()
    .padStart(decimals, '0')
    .replace(/0+$/, '');

  return fraction ? `${whole}.${fraction}` : whole;
}

parseUnits() accepts an amount string, never a JavaScript floating-point value. It rejects negative signs, scientific notation, grouping separators, and inputs with more precision than the asset allows. It doesn't silently round or truncate.

formatUnits() does the reverse using integer division and remainder. It removes unnecessary trailing zeros for display but doesn't change the underlying amount.

The 0–30 decimal-place check is a protective limit for this tutorial, not a blockchain-wide rule. A production system must define limits based on the assets and inputs it actually supports.

Add amounts without floating-point math

With eight decimal places:

import { parseUnits, formatUnits } from './amounts.mjs';

const first = parseUnits('0.1', 8);  // 10000000n
const second = parseUnits('0.2', 8); // 20000000n
const total = first + second;        // 30000000n

console.log(formatUnits(total, 8)); // '0.3'

The values are exact because we're adding integers. No Number conversion or toFixed() call is needed.

The same functions handle one satoshi:

parseUnits('0.00000001', 8); // 1n
formatUnits(1n, 8);          // '0.00000001'

They also preserve a base-unit amount larger than JavaScript's maximum safe integer:

const amount = '90071992.54740993';
const units = parseUnits(amount, 8);

console.log(units);                 // 9007199254740993n
console.log(formatUnits(units, 8)); // '90071992.54740993'

Rounding is a business rule, not a formatting trick

Exact integer arithmetic doesn't remove the need for rounding. It makes rounding explicit.

For example, imagine an illustrative fee of 25 basis points (0.25%). If the policy requires rounding the fee up to the nearest smallest unit, for a non-negative amount we can use:

const amountUnits = parseUnits('0.12345678', 8);
const feeBps = 25n; // 25 / 10,000 = 0.25%

const feeUnits = (amountUnits * feeBps + 9_999n) / 10_000n;

console.log(formatUnits(feeUnits, 8)); // '0.00030865'

Why add 9_999n? Integer division truncates the fractional part, so that expression implements ceiling division for non-negative integers. If a fee policy requires rounding down, you'd use a different calculation.

Don't reuse a rounding rule blindly. Trading quotes, displayed estimates, payout amounts, and fees can have different requirements. When converting between assets, also specify the quote's price representation and which side of the conversion is rounded. BigInt alone does not solve exchange-rate arithmetic.

Keep JSON boundaries explicit

JSON.stringify() does not serialize a BigInt directly:

JSON.stringify({ amount: 10000000n });
// Throws TypeError

Instead, define an API format that uses a decimal string for the base-unit integer, plus the asset and precision metadata:

const payload = {
  asset: 'BTC',
  amount_units: total.toString(),
  decimals: 8,
};

const json = JSON.stringify(payload);
// {"asset":"BTC","amount_units":"30000000","decimals":8}

When reading this data, validate the asset, network, precision, and amount string before reconstructing a BigInt. Treat the JSON fields as an explicit contract, not something to guess from the displayed number.

Test the edge cases

Create amounts.test.mjs next to amounts.mjs:

import test from 'node:test';
import assert from 'node:assert/strict';
import { parseUnits, formatUnits } from './amounts.mjs';

test('adds 0.1 and 0.2 exactly', () => {
  const a = parseUnits('0.1', 8);
  const b = parseUnits('0.2', 8);
  assert.equal(formatUnits(a + b, 8), '0.3');
});

test('preserves values beyond Number.MAX_SAFE_INTEGER', () => {
  const amount = '90071992.54740993';
  assert.equal(parseUnits(amount, 8), 9007199254740993n);
  assert.equal(formatUnits(parseUnits(amount, 8), 8), amount);
});

test('supports one satoshi and zero-decimal assets', () => {
  assert.equal(parseUnits('0.00000001', 8), 1n);
  assert.equal(formatUnits(1n, 8), '0.00000001');
  assert.equal(parseUnits('12', 0), 12n);
  assert.equal(formatUnits(12n, 0), '12');
});

test('formats trailing zeros without changing the amount', () => {
  assert.equal(formatUnits(parseUnits('1.2300', 6), 6), '1.23');
});

test('rejects excess precision', () => {
  assert.throws(() => parseUnits('0.000000001', 8), RangeError);
});

test('rejects invalid amount formats', () => {
  assert.throws(() => parseUnits('-1', 8), TypeError);
  assert.throws(() => parseUnits('1e-8', 8), TypeError);
  assert.throws(() => parseUnits(0.1, 8), TypeError);
});

Run them with a modern version of Node.js:

node --test amounts.test.mjs

These cases check exact addition, maximum-safe-integer boundaries, the smallest supported unit, zero-decimal assets, display formatting, and invalid input.

For production use, you'd also want limits on input length, asset metadata validation, explicit overflow rules for external systems, property-based tests, and round-trip tests over a much larger set of values.

Common mistakes worth avoiding

Converting a user-entered amount to Number first. Once precision is lost, a later BigInt conversion cannot recover it.
Using toFixed() as the calculation strategy. It formats a floating-point value; it does not turn previous arithmetic into exact decimal arithmetic.
Assuming all assets use 18 decimals. Precision must come from trusted metadata for the specific asset and network.
Mixing smallest units from different assets. 1000n satoshis and 1000n wei are not comparable amounts.
Ignoring the rounding policy. An exact integer calculation can still implement the wrong fee or conversion rule.
Serializing BigInt as a JSON number. Preserve base-unit counts as strings when exchanging data with systems that may not safely represent large integers.

Key takeaways

A reliable money-handling boundary in JavaScript can be summarized as:

Decimal input string → validated smallest-unit BigInt → integer arithmetic → explicit rounding → decimal output string.

This pattern is straightforward, testable, and avoids accidental floating-point precision loss. It does not replace asset validation, appropriate arithmetic libraries for complex price ratios, or a careful review of financial requirements. But it gives the rest of the application something valuable: exact amounts to work with.

References

AI disclosure: The initial article draft and code examples were generated with AI assistance.

Introducing CryptoDeepApp: Instant Crypto Swaps, Token Analysis, and Portfolio Tools

Jayden Cristian — Wed, 30 Sep 2026 22:02:05 +0000

CryptoDeepApp is a cryptocurrency platform built around one main idea: bring crypto exchange, token research, and portfolio tools together in one place.

The platform started with crypto analytics, but instant cryptocurrency exchange has become one of its core products.

In this post, I want to give a quick overview of what CryptoDeepApp currently provides and how the main parts of the platform fit together.

Instant Crypto Swaps

CryptoDeepApp allows users to exchange cryptocurrencies through a simple swap flow.

Users can:

choose the asset they want to send
choose the asset they want to receive
select supported blockchain networks
enter receiving and refund addresses
choose between floating and fixed exchange rates
review exchange limits and route information before starting

Once an exchange is created, users can track its progress through several stages:

Waiting → Deposit → Exchange → Sending → Success

If the deposit window expires before funds are received, the exchange can move to an Overdue state.

The goal is to make the entire swap process transparent instead of hiding the transaction behind a single loading screen.

Fixed and Floating Rates

CryptoDeepApp supports two exchange modes.

Floating rate

The final exchange amount follows the market rate while the swap is being processed.

This can provide a rate closer to the live market, but the amount received may change as market conditions move.

Fixed rate

The exchange rate is locked for the swap according to the available quote.

This gives the user more certainty about the expected amount they will receive.

Solana Token Analyzer

CryptoDeepApp also includes a token analysis tool for Solana assets.

The analyzer brings together multiple types of information, including:

token overview
token rating
top holders
24-hour activity
liquidity
risk indicators
mint and freeze permissions
developer wallet information
social links
AI-assisted analysis

The purpose is to give users a quick view of a token's structure and market activity before they decide to research it further.

Portfolio Tracking

Users can also save assets to a portfolio and monitor their positions.

Portfolio tools include:

initial and current value
profit and loss
percentage performance
purchase history
target prices
price alerts
performance charts

Supported Solana assets can also be opened directly in the Token Analyzer.

API Integrations

CryptoDeepApp provides API functionality for partners who want to integrate exchange-related features into their own products.

Potential integrations include:

wallets
crypto applications
portfolio tools
aggregators
payment products
other Web3 services

The idea is to make the exchange layer usable both through the CryptoDeepApp interface and through external products.

Affiliate Tools

CryptoDeepApp also includes an affiliate system for partners.

Partners can create referral links, track referred swaps, view earnings, and manage payouts through their dashboard.

This creates another way for crypto communities, creators, and products to integrate with the platform without building a full API integration.

Building the Platform

From a technical perspective, CryptoDeepApp combines several different systems:

frontend web applications
backend APIs
blockchain integrations
exchange infrastructure
real-time transaction states
token data providers
monitoring
portfolio and notification services

That makes reliability and clear state management especially important.

Over time, we plan to use this DEV organization to share more about the technical side of building CryptoDeepApp — including API integrations, exchange workflows, infrastructure, monitoring, and blockchain data processing.

Learn More

CryptoDeepApp is available at:

https://cryptodeep.app

API documentation:

https://cryptodeep.app/api-docs

How the platform works:

https://cryptodeep.app/how-it-works

5 Lessons I Learned Building API-Driven Fintech Products

Jayden Cristian — Wed, 30 Sep 2026 21:37:35 +0000

Modern fintech products often look simple from the user's perspective: choose an asset, enter some details, confirm an action, and wait for the result.

Behind that interface, however, there is usually a lot of API orchestration, state management, error handling, and monitoring.

Here are five practical lessons I’ve learned while working on API-driven web products.

1. Treat external APIs as unreliable by default

Even a stable provider can experience timeouts, rate limits, delayed responses, or temporary outages.

Instead of assuming every request will succeed, design integrations with:

request timeouts
retries with backoff
clear error states
provider health checks
logging and monitoring

A failed API request should not automatically become a failed user experience.

2. Make state transitions explicit

For workflows that involve multiple steps, a clear state model makes the application much easier to maintain.

For example:

waiting → processing → sending → completed

Explicit states help both the frontend and backend understand what is happening and make debugging much easier.

3. Never trust only the frontend

Validation should exist on both sides.

The frontend improves user experience, but the backend should always validate:

required fields
supported assets or networks
numerical limits
addresses and identifiers
authorization
request integrity

Anything coming from the client should be treated as untrusted input.

4. Monitoring is part of the product

Logs are useful, but production systems need more than logs.

It helps to monitor:

API response times
failed requests
provider availability
error rates
background jobs
infrastructure health

The earlier a problem is detected, the easier it is to fix before users notice it.

5. Keep integrations isolated

When possible, avoid spreading provider-specific logic throughout the application.

A better approach is to create a separate integration layer:

Application → Internal Service → External Provider

This makes it easier to replace a provider, add another one, or change API behavior without rewriting the rest of the system.

Final thoughts

Building API-driven fintech products is less about making individual requests and more about designing for uncertainty.

Good architecture should assume that networks fail, providers change, data can be delayed, and unexpected states will eventually happen.

The more of those situations you handle intentionally, the more reliable the product becomes.

DEV Community: Jayden Cristian

Why "just retry it" can be dangerous

First, classify the failure

1. Put a timeout on each attempt

2. Add exponential backoff with jitter

3. Respect Retry-After without retrying too early

4. Build a reusable JSON retry client

5. Use it for a read-only API request

6. What about POST and duplicate operations?

7. Test the retry policy without external requests

8. Production concerns beyond this demo

Key takeaways

References

Modeling Blockchain Deposit Workflows with a State Machine in Node.js

The duplicate delivery problem

Two identities, two different jobs

Why a processed-events check alone is not enough

Build a testable model in plain Node.js

Test duplicates and concurrent deliveries

Move the guarantee into MongoDB

An outbox record is not an exactly-once payout

Edge cases worth designing before production

Key takeaways

References

Handling Cryptocurrency Amounts in JavaScript Without Floating-Point Errors

Why a small rounding error matters

Store amounts in the smallest unit

Why BigInt is useful

Build two small utilities

Add amounts without floating-point math

Rounding is a business rule, not a formatting trick

Keep JSON boundaries explicit

Test the edge cases

Common mistakes worth avoiding

Key takeaways

References

Introducing CryptoDeepApp: Instant Crypto Swaps, Token Analysis, and Portfolio Tools

Instant Crypto Swaps

Fixed and Floating Rates

Floating rate

Fixed rate

Solana Token Analyzer

Portfolio Tracking

API Integrations

Affiliate Tools

Building the Platform

Learn More

5 Lessons I Learned Building API-Driven Fintech Products

1. Treat external APIs as unreliable by default

2. Make state transitions explicit

3. Never trust only the frontend

4. Monitoring is part of the product

5. Keep integrations isolated

Final thoughts

Why `BigInt` is useful