Idempotency Keys for Blockchain Data Imports
Make repeated import requests safe by scoping idempotency keys to an operation and payload, while keeping request identity separate from event deduplication.
Overview
When translating these concepts into an integration, keep the scope described by the wallet history api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
An idempotency contract lets a caller repeat an operation without unintentionally creating its effects twice. It requires defined key scope, payload binding and retention, not just an extra request header.
Bind the key to the operation
Include tenant or owner context and operation type in the key namespace. Store a digest or equivalent comparison of the relevant request payload. Reusing a key for a different wallet or range should produce a defined conflict rather than silently return an unrelated earlier result. Keep credential values out of stored request fingerprints.
Worked example: retry after lost response
An import request commits but its response is lost. The caller repeats the same key and payload. The service returns the existing operation result or state rather than starting a second import. A changed date range with that key is rejected under the declared conflict policy.
Test concurrent requests
Two simultaneous requests with the same key must not both reserve the operation independently. Define pending and failed-result behaviour, key expiry and ownership checks. Event-level deduplication is still necessary because two intentionally different imports can contain overlapping chain records. Idempotency protects operation effects, while event identity protects the imported evidence layer.
A practical acceptance test
Submit identical key and payload concurrently, then repeat after a simulated lost response. Exactly one operation should be reserved. Reuse the key with a different wallet range and assert the documented conflict. Finally submit a distinct operation overlapping the same events to verify that event-level deduplication still works independently of request idempotency.
Questions about the topic
Frequently asked questions
Does an idempotency header alone guarantee safety?
No. The server must implement a durable, scoped contract.
Does import idempotency replace event deduplication?
No. Overlapping distinct imports can contain the same events.
Standards & technical documentation