Sui RPC Patterns for Events, Checkpoints, and Scale

Teams usually learn Sui by reading objects, fetching balances, and wiring a wallet. The trouble starts later. Real Sui RPC patterns for event ingestion, checkpoint tracking, pagination, and replay after outages look very different from a prototype that only calls a few read methods on demand.

Sui’s data model rewards precision. If your backend treats every query like a simple object lookup, you can miss updates, over-fetch data, or create indexers that silently drift from chain state. Wallets, explorers, alerting systems, and analytics backends need a design that separates user-facing reads from chain-following ingestion.

This guide focuses on production patterns for Sui: when to poll RPC, when to consume checkpoints, how to store cursors safely, and how to recover after missed windows without corrupting your database. If you need a managed endpoint while you scale these workloads, Nadcab RPC exposes Sui at https://rpc.nadcab.com/sui/<your-api-key> with one API key across many networks and both HTTPS and WebSocket access.

Why Sui backends break after the first prototype

A prototype usually does three things well: fetch a known object, list owned objects, and display a recent transaction. Those are interactive reads. They are not the same as continuous ingestion.

Production systems fail when they assume RPC responses arrive in a perfect order and can be stitched together later. On Sui, that often leads to three common issues:

• State gaps: an app reads current objects but has no reliable history of how they changed.
• Cursor mistakes: a backend uses pagination cursors like offsets and accidentally skips or reprocesses records.
• Recovery failures: after downtime, the service restarts from “latest” instead of replaying a known checkpoint range.

If you already reviewed object ownership and object reads, this article continues from there. For object-level fundamentals, see Nadcab Labs’ Sui RPC guide for object reads, ownership, and scaling.

The durable rule is simple: reads answer questions from users; ingestion builds your own trustworthy local view. You should not use the same request path for both.

Sui data access patterns: objects, events, and checkpoints

Think about Sui access in three layers. Each layer answers a different backend question.

1. Object reads for current state

Use object reads when you already know what you need: an object ID, an owner address, or a transaction digest. This is the right path for UI requests and narrow API endpoints.

Examples:

• Load a user’s current balance-holding objects.
• Fetch a package object for metadata.
• Resolve one transaction after a user clicks activity details.

These calls are cheap in application design terms, but they do not tell you what happened while your service was offline.

2. Event queries for app-specific activity

Events are useful when your contracts emit clean application signals and your backend only cares about those signals. For example, a marketplace might emit listing, purchase, and cancel events. An event-driven worker can index those directly instead of reconstructing behavior from every object mutation.

Events are best when:

• You own the Move packages and control event schema.
• You need business-level actions, not every low-level object write.
• You can tolerate query pagination and occasional replay.

Events are less ideal if you need full-chain completeness for unrelated packages or broad analytics across many contracts.

3. Checkpoints for authoritative chain-following

Checkpoints are the better foundation for robust ingestion. They give you a monotonic sequence to track. Instead of asking “what is new right now?” you ask “what checkpoint comes after the last one I committed?” That shift is what makes recovery safe.

Use a checkpoint consumer when you need:

• Replay from a precise position after downtime.
• Deterministic ordering for indexing jobs.
• Cross-table consistency in your database.
• A broad or long-running ingest pipeline.

For many production systems, the pattern is: checkpoints for ingestion, object reads for serving, events as an optimization for app semantics.

When to poll RPC and when to build a checkpoint consumer

Polling RPC is not wrong. It is just easy to misuse.

Poll RPC when the scope is small and the blast radius is low

Polling is acceptable for narrow workflows:

• A small wallet backend watching a limited set of addresses.
• An admin dashboard checking the latest status of a controlled package.
• A cron job that enriches recent transactions for internal reporting.

In these cases, a simple loop with cursor persistence can be enough. You still need idempotency and replay, but you may not need a full chain-ingestion service.

Build a checkpoint consumer when correctness matters more than simplicity

If your product is public-facing, multi-tenant, or expected to survive outages cleanly, move to checkpoints early. A checkpoint consumer lets you process data in order, write durable offsets, and backfill any missed range later.

Typical examples:

• Wallets: transaction history and token activity should be reproducible after a worker restart.
• Explorers: broad coverage requires ordered ingestion instead of ad hoc reads.
• dApps with accounting logic: reward distribution, settlement, and audit trails need replay-safe history.

If your team wants one endpoint that can serve both early polling and later scale-out workers, Nadcab Cloud is useful because it keeps the connection model simple while you evolve your architecture. For teams that want their own nodes behind managed routing, Nadcab Core fits better.

https://rpc.nadcab.com/sui/<your-api-key>

Pagination, cursors, and replay-safe indexing patterns

The biggest indexing bug is treating cursors like page numbers. They are not. A cursor is a continuation token or position marker. Your job is to persist it exactly and only advance it after your writes commit successfully.

Golden rules for cursors

• Store the cursor and processed range in the same transaction as your indexed data when possible.
• Never overwrite a cursor before downstream writes are durable.
• Expect reprocessing and make writes idempotent.
• Separate “fetched” from “committed” state in your worker.

A replay-safe worker model

1. Load last committed cursor or checkpoint from the database.
2. Request the next page or next checkpoint batch from RPC.
3. Transform records into deterministic rows keyed by stable identifiers.
4. Upsert rows idempotently.
5. Commit the new cursor or checkpoint only after the upserts succeed.

This model intentionally allows duplicates on retry. Duplicates are cheaper than gaps.

Example: polling Sui RPC with a persisted cursor

The exact method set may vary by client, but the pattern below is what matters. The endpoint uses the Nadcab RPC Sui slug and your API key.

const RPC_URL = 'https://rpc.nadcab.com/sui/<your-api-key>';

async function rpc(method, params) {
  const res = await fetch(RPC_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 1,
      method,
      params
    })
  });

  if (!res.ok) {
    throw new Error(`HTTP ${res.status}`);
  }

  const json = await res.json();
  if (json.error) {
    throw new Error(json.error.message || 'RPC error');
  }
  return json.result;
}

async function ingestEvents(loadCursor, saveBatch) {
  let cursor = await loadCursor();
  let hasNextPage = true;

  while (hasNextPage) {
    const result = await rpc('suix_queryEvents', [
      {
        MoveEventType: '0xYOUR_PACKAGE::market::ItemPurchased'
      },
      cursor,
      100,
      true
    ]);

    const rows = result.data.map((event) => ({
      id: event.id.txDigest + ':' + event.id.eventSeq,
      txDigest: event.id.txDigest,
      eventSeq: event.id.eventSeq,
      packageId: event.packageId,
      sender: event.sender,
      parsedJson: event.parsedJson,
      timestampMs: event.timestampMs
    }));

    await saveBatch({
      rows,
      nextCursor: result.nextCursor,
      hasNextPage: result.hasNextPage
    });

    cursor = result.nextCursor;
    hasNextPage = result.hasNextPage;
  }
}

In this example, saveBatch should upsert rows and persist nextCursor atomically. If the process crashes before that transaction commits, the same page can be fetched again safely.

For broader RPC hygiene patterns, Nadcab Labs also published a practical guide on authentication, error handling, and RPC setup.

Designing reliable Sui ingestion for wallets, explorers, and apps

Wallet pattern: track a bounded set of owners

A wallet backend usually cares about a known list of addresses. Start with targeted queries and a small checkpoint-based history process. Store these entities separately:

• Accounts you watch
• Objects currently owned
• Transactions affecting those owners
• Last committed checkpoint or per-stream cursor

Do not recompute current balances only from recent activity unless you also have a reconciliation job. Periodically compare indexed state against direct object reads to catch drift.

Explorer pattern: make checkpoints your source of truth

An explorer needs broad chain coverage, so event-only indexing is too narrow. Use checkpoints as the ingestion backbone and derive secondary tables for transactions, packages, addresses, and custom app activity.

Keep your schema layered:

• Raw ingestion tables: minimal transformation, append-friendly.
• Normalized chain tables: transactions, events, object changes.
• Serving tables: precomputed views for API and UI latency.

This layering lets you replay normalization logic without re-fetching the entire chain every time your product logic changes.

App backend pattern: mix checkpoints and direct reads

Many apps do not need full explorer coverage. They need confidence for their own contracts and responsive APIs for users. A practical design is:

• Checkpoint consumer for durable history of your packages.
• Event indexing for domain actions.
• Direct object reads for immediate page loads.
• Scheduled reconciliation for high-value tables.

If your team operates in regulated or enterprise environments, dedicated infrastructure such as Nadcab Craft can help when you need custom authentication, compliance logging, or an enterprise SLA around the RPC layer.

Common Sui RPC failure modes and how to recover cleanly

Failure mode 1: restarting from latest

This is the classic data-loss bug. A worker crashes, restarts, fetches only the newest data, and permanently misses the gap.

Fix: restart from the last committed checkpoint or cursor, never from “latest,” unless the stream is intentionally lossy.

Failure mode 2: duplicate rows after retries

Retries happen. Network timeouts happen. If your primary key is weak, retries produce duplicate logical records.

Fix: define deterministic unique keys, such as transaction digest plus event sequence, and use idempotent upserts.

Failure mode 3: slow consumer drift

Your service keeps working but falls further behind because enrichment is too heavy inside the ingest loop.

Fix: split ingestion from enrichment. First store chain facts. Then run async processors that decorate records for search, analytics, or notifications.

Failure mode 4: provider or region instability

Even a good backend design suffers if the RPC path is brittle. You want visibility into gateway health and predictable failover behavior.

Fix: use a managed gateway with routing and monitor the live status page. Nadcab RPC uses smart routing across providers and regions, which is useful when your Sui workers should keep a stable endpoint while the backend path is optimized behind the scenes.

Failure mode 5: unbounded backfills

Teams often discover they need historical data, then start an open-ended replay that competes with live traffic.

Fix: separate live consumers from backfill jobs, cap batch sizes, and prioritize fresh checkpoints while backfill catches up in parallel.

How to connect Sui apps with a managed RPC endpoint

The simplest endpoint pattern is:

https://rpc.nadcab.com/sui/<your-api-key>

You can create an API key from the Nadcab RPC console login and review network details in the supported networks and endpoints list. Nadcab RPC supports Sui alongside many other networks under one API key, which is helpful for teams building cross-chain dashboards, wallets, or bridge-adjacent tooling.

If you are choosing deployment shape:

• Nadcab Cloud fits shared auto-scaling endpoints and early production workloads.
• Nadcab Core fits teams that want their own nodes with Nadcab’s routing engine.
• Nadcab Craft fits dedicated clusters and stricter operational controls.

For budgeting, the public RPC pricing page lists pay-as-you-go at $0.375 per 1M compute units and Nadcab Cloud from $10, with no rate tiers. That matters for ingestion planning because your cost model should be tied to request patterns, batch sizing, and how much of your workload can be served from your own indexed database instead of repeated RPC reads.

A practical checklist for moving Sui RPC workloads to production

• Define whether each backend feature is a read path or an ingestion path.
• Use object reads for current state, not as a substitute for historical indexing.
• Pick checkpoints as the default source for reliable long-running ingestion.
• Persist cursors or checkpoint numbers only after downstream writes commit.
• Use deterministic primary keys and idempotent upserts everywhere.
• Split raw chain ingestion from enrichment and API-serving tables.
• Keep live consumers and historical backfill workers separate.
• Run periodic reconciliation against direct RPC reads for important balances or ownership views.
• Monitor endpoint health with the status page and instrument consumer lag in your app.
• Document replay procedures before the first incident, not after it.

If your architecture spans multiple chains or you are standardizing team practices, the Nadcab Labs post on web3 infrastructure, nodes, RPCs, and APIs is a useful companion. For post-incident operations, the guide on RPC credential rotation after an incident is also worth bookmarking.

Final Thoughts

Strong Sui backends are less about clever queries and more about choosing the right ingestion boundary. Object reads are excellent for serving current state. Events are useful for application semantics. Checkpoints are what make long-running, replayable indexing dependable.

The practical version of good Sui RPC patterns is to stop thinking in pages and start thinking in committed positions. Persist progress carefully, design for retries, and keep your serving layer separate from chain-following workers. When you need a managed endpoint for Sui while your system grows from prototype to production, Nadcab RPC docs and the Sui endpoint at https://rpc.nadcab.com/sui/<your-api-key> give you a straightforward path to implement these patterns cleanly.