Production & Best Practices

To build resilient, high-performance Web3 applications with the TUWA Ecosystem, developers should align their systems with the core operational guidelines of the platform.

1. Idempotency & Re-entrancy Protection

Quasar enforces strict uniqueness constraints on transaction ingestion to ensure safe retries:

• Transaction Key (txKey): Every transaction synchronized via Pulsar requires a unique txKey (e.g. tx_local_18f2...), typically derived from the blockchain transaction hash or a deterministic client-side identifier.
• Safe Re-entrancy: Resubmitting a transaction with an identical txKey is idempotent. Quasar will update existing record states without duplicating entries or double-charging organization quotas.

2. Quota Weighting & Accounting

Quasar measures infrastructure usage via a granular weighting system:

3. Smart Degradation & Quota Thresholds

When an organization’s quota balance is exhausted (currentUsage > limit), the Quasar Engine protects application UX through Smart Degradation:

• Fast Mode (remaining >= 0): Real-time transaction ingestion and instant webhook dispatches when organization quota balance is positive (currentUsage <= limit).
• Lazy Mode (remaining < 0): Quota depleted (currentUsage > limit); transaction syncing requests (POST /v1/engine/pulsar/sync) bypass immediate HTTP errors to preserve client-side dApp UX, queueing transactions asynchronously via BullMQ and Redis.
• Webhook Dispatches: Outbound webhook deliveries pause when quota is depleted (remaining < 0) until the organization quota balance is replenished.
• Free Read Access: Transaction history queries (GET /v1/engine/pulsar/history) carry 0.0 quota weight and remain fully accessible.

4. Cache Eviction & Key Propagation

The high-performance API layer (api.tuwa.io) uses the IronDomeGuard to cache application metadata (IP whitelists, domain rules, and key hashes) in Redis under {key}:meta:

• Eviction Triggers: Modifying IP whitelists, updating domain constraints, or rolling secret keys immediately dispatches eviction events to purge Redis caches.
• Propagation Latency: Allow up to 60 seconds for global multi-region edge caches to fully evict old metadata. After rolling a key in the Dashboard, immediately update your backend environment variables (.env) with the new Secret Key.

5. Webhook Security & Receiver Design

• HTTPS Required: Production webhooks must target secure https:// URLs (http:// allowed only in development environments).
• 10-Second Timeout: Webhook receivers must return an HTTP 200 OK response within 10 seconds. Defer long-running database tasks or external API calls to background job queues.
• Timing-Safe Verification: Always verify the x-quasar-signature header using crypto.timingSafeEqual and your raw request body string before processing webhook events.
• Manual Resend: Webhooks that fail after multiple automated retries can be manually restarted from the Delivery Logs in the Quasar Dashboard.