Receipts give you cryptographic proof of the exact time, accurate to the millisecond, that a transaction occurred.


For implementation and usage details, see the SDK documentation for bundlr.uploadWithReceipt() and bundlr.utils.getReceipt().

Receipts & Timestamps

Blockchains rely on timestamps to sequence the order of transactions and blocks. Transaction sequencing plays a critical role in blockchain security as it ensures that all transactions are recorded in the correct order, and that order is never changed.

Receipts provide cryptographic proof of a timestamp. This creates a secure and tamper-proof sequence of all transactions, enabling proof of authenticity, permanence, and provenance.

Ordering & Streaming

Ordering and streaming applications process and deliver data in real-time. They're commonly used for messaging, event processing, and data integration. They transfer high data volumes between independent applications while maintaining high performance and scalability. Popular examples include Apache Kafka and RabbitMQ.

Users could use Bundlr's receipts to:

  • Build a category-based event streaming application by using Bundlr’s GraphQL API.
  • Build a "mutability layer" by using a sequence of transactions all tied to a single piece of information. The most recent transaction represents the current version of the information, while the chronological history shows previous versions.

Why Use Signed Receipts?

Cryptographically signed receipts open up new development options for builders. For example:

  1. Sequential ordering of posts, likes and comments for a decentralized social protocol.
  2. Sequencial ordering of data generated by a group messaging protocol.
  3. Automatically adjudicating music copyright claims.
  4. Preserving history, ensuring it's not manipulated over time.
  5. Preserving scientific research using Bundlr's pay-once, store-forever model.

Receipt Permanence

Upon posting a transaction to Bundlr, a receipt is immediately returned to the user.

Bundlr maintains an internal registry of all receipts, which can be queried whenever a receipt is needed. These receipts are stored in a centralized fashion, which may be sufficient for users comfortable with the trust assumptions of centralized services.

Users also have the option to use Bundlr to store the receipt on Arweave. These receipts inherit Arweave’s permanence, meaning you can verify transaction sequencing at any time, even if Bundlr is no longer available.

Receipt Format

Receipts are a JSON object with the following format:

  id: '1Txlbl5NgEqUbIkDnnunHC0gFx0n8_Y92zAsoX54kI8',
  timestamp: 1676891681110,
  version: '1.0.0',
  public: '...',
  signature: '...',
  deadlineHeight: ...,
  block: ...,
  validatorSignatures: [],
idTransaction id (used to download the data)
timestampTimestamp (UNIX milliseconds) of when the transaction was created
versionThe version of this JSON file, currently 1.0.0
publicPublic key of the bundler node used
signatureA signed deep hash of the JSON receipt
deadlineHeightThe block number by which the transaction must be finalized on Arweave
validatorSignaturesReserved for future use once we're decentralized

Verifying Receipts

You may need to verify a receipt at some point after it was issued. For example, if your application’s security depends on the order of transactions, you can then verify every receipt to ensure its order has not been tampered with.

The receipt contains a signature field, which is generated by creating a deep hash of information from the receipt, including transaction ID and timestamp. It is then signed it by Bundlr.

Using the Bundlr SDK you can verify the signature using the using the same values from the receipt along with the supplied public key.

Timestamp Generation

Bundlr records the precise time of each transaction with a UNIX timestamp in milliseconds. This timestamp is generated by the node that first receives and verifies the transaction.

Currently, the timestamp is generated by a centralized service, but as Bundlr moves towards a more decentralized infrastructure, a decentralized timestamp validator network will be introduced. This validator network will be compromised of external actors who validate the authenticity of the timestamps, providing additional assurances about the transaction's sequence and provenance.