# ANS-102: Bundled Data - JSON Serializationopen in new window

Status: Standard

# Abstract

This document describes the data format and directions for reading and writing bundled data. Bundled data is a way of writing multiple logical data transactions (referred to as DataItems in this document) into one top level transaction. A DataItem shares many of the same properties as normal data transaction, in that it has an owner, data, tags, target, signature, and id. It differs in that it has no ability to transfer tokens, and no reward, as the top level transaction pays the reward for all bundled data.

# Motivation

Bundling multiple logical data transactions into one transaction provides a number of benefits:

• To allow delegation of payment for a DataItem to a 3rd party, while maintaining the identity and signature of person who created the DataItem, without them needing to have a wallet with funds.

• Allow multiple DataItems to be written as a group.

• To increase the throughput of logically independent data writes to the Arweave network

# Reference Implementation

There is a reference implementation for the creation, signing, and verification of DataItems and working with bundles in TypeScriptopen in new window

# Specification

# 1. Transaction Format

# 1.1 Transaction Tags

A bundle of DataItems MUST have the following two tags present

• Bundle-Format a string describing the bundling format. The format for this standard is json
• Bundle-Version a version string. The version referred to in this standard is 1.0.0

# 1.2 Transaction Body Format

This format for the transaction body is a JSON object in the following format

{
  items: [
    { DataItem },
    { DataItem }
  ]
}

# 1.3 DataItem Format

A DataItem is a JSON object that has similar properties to a transaction:

B64U Encoding indicates the field is Base64Url encoded binary.

All properties MUST be present, for optional values the value in 'Empty Value' MUST be used.

A tag object is a JSON object with the following two keys. A tag object MUST NOT have any other keys.

The fields in the DataItem and Tags objects can be handled in an identical way as their counterpart in a regular Arweave transaction.

The nonce field in DataItem is optional, and is an arbitrary value to allow bundling gateways to provide protection from replay attacks against them or their users.

# 2. DataItem signature and id

The signature, and id for a DataItem is built in a manner similar to Arweave 2.0 transaction signing. It uses the Arweave 2.0 deep-hash algorithm. The 2.0 deep-hash algorithm operates on arbitrarily nested arrays of binary data, i.e a recursive type of DeepHashChunk = Uint8Array | DeepHashChunk[].

There is reference implementations for the deep-hash algorithm in TypeScriptopen in new window and Erlangopen in new window

To generate a valid signature for a DataItem, the contents of the DataItem and static version tags, are passed to the deep-hash algorithm to obtain a message. This message is signed by the owner of the DataItem to produce the signature. The id of the DataItem, is the SHA256 digest of this signature.

The exact structure and content passed into the deep-hash algorithm to obtain the message to sign is as follows:

[
  utf8Encoded("dataitem"),
  utf8Encoded("1"),
  owner,
  target,
  nonce,
  [
    ... [ tag.name, tag.value ],
    ... [ tag.name, tag.value ],
    ...
  ],
  data
]

# 3. Expanding a bundle of DataItems

To read and expand a bundle of DataItems, each DataItem in the items should be verified using the verification algorithm. Individual items that fail verification MUST be discarded.

In rare cases, an identical DataItem may exist in more that one transaction. That is, the contents and id of the DataItem are identical but exist in multiple Arweave transactions. Since they are identical, any of the copies can be discarded.

# 4. Writing a bundle of DataItems

To write a bundle of DataItems, each DataItem should constructed and signed, and placed in a transaction with the transaction body format and transaction tags specified in Section 1. Transaction Format.