Mutating Entities

All entity mutations are sent as standard Ethereum transactions to a special Arkiv address. The transaction data field carries an encoded payload that describes one or more operations.

Property	Value
Arkiv Address	`0x00000000000000000000000000000061726b6976`
Block Time	2 seconds
Transaction Value	0 (no ETH transferred)

Payload Structure

The transaction data is a 5-element array:

[
  creates,            // index 0
  updates,            // index 1
  deletes,            // index 2
  extensions,         // index 3
  ownershipChanges    // index 4
]

Each element is an array of operations of that type.

Operation Formats

Create (index 0)

Index	Field	Type	Description
0	expiresInBlocks	number	`ceil(seconds / 2)`
1	contentType	string	MIME type
2	payload	string	Entity content
3	stringAttributes	`[[key, value], ...]`	String-typed attributes
4	numberAttributes	`[[key, value], ...]`	Number-typed attributes

Update (index 1)

Index	Field	Type	Description
0	entityKey	hex string	`0x`-prefixed entity key
1	contentType	string	MIME type
2	expiresInBlocks	number	`ceil(seconds / 2)`
3	payload	string	Entity content
4	stringAttributes	`[[key, value], ...]`	String-typed attributes
5	numberAttributes	`[[key, value], ...]`	Number-typed attributes

Delete (index 2)

Each delete entry is just the entity key as a 0x-prefixed hex string.

Extend (index 3)

Index	Field	Type	Description
0	entityKey	hex string	`0x`-prefixed entity key
1	expiresInBlocks	number	`ceil(additionalSeconds / 2)`

Change Ownership (index 4)

Index	Field	Type	Description
0	entityKey	hex string	`0x`-prefixed entity key
1	newOwner	hex string	`0x`-prefixed address of the new owner

Attributes

Attributes are split into two arrays by value type:

String attributes — [["category", "documentation"], ["version", "1.0"]]
Number attributes — [["priority", 5], ["count", 100]]

Encoding Pipeline

The payload goes through four stages before inclusion in a transaction:

Human-readable JSON — Start with a JSON array matching the 5-element structure.
Hex-encode all leaf values — Convert every leaf to a 0x-prefixed hex string. Strings become hex-encoded UTF-8, numbers become hex-encoded integers, and 0 becomes "0x".
RLP-encode — The nested hex structure is RLP-encoded into a flat byte sequence.
Brotli-compress — The RLP bytes are compressed with Brotli. The output is hex-encoded with a 0x prefix.

Example: Creating an Entity

Goal: Create an entity with payload {"message": "Hello from Arkiv"}, content type application/json, 30-day expiration, string and number attributes.

Step 1 — Build the JSON payload

[
  [
    [
      1296000,
      "application/json",
      "{\"message\":\"Hello from Arkiv\"}",
      [["category", "example"], ["version", "1.0"]],
      [["priority", 0], ["count", 100]]
    ]
  ],
  [],
  [],
  [],
  []
]

Step 2 — Hex-encode leaf values

[
  [
    [
      "0x13c680",
      "0x6170706c69636174696f6e2f6a736f6e",
      "0x7b226d657373616765223a2248656c6c6f2066726f6d2041726b6976227d",
      [
        ["0x63617465676f7279", "0x6578616d706c65"],
        ["0x76657273696f6e", "0x312e30"]
      ],
      [
        ["0x7072696f72697479", "0x"],
        ["0x636f756e74", "0x64"]
      ]
    ]
  ],
  [],
  [],
  [],
  []
]

Step 3 — RLP-encode

rlp encode '<hex-encoded-json>'

Step 4 — Brotli-compress and hex-encode

echo "$RLP_HEX" | sed 's/^0x//' | xxd -r -p | brotli | xxd -p | tr -d '\n' | sed 's/^/0x/'

This final hex string is the transaction data field.

Signing and Sending

Field	Value
`to`	`0x00000000000000000000000000000061726b6976`
`value`	`0`
`data`	the Brotli-compressed hex payload

Broadcasting

curl -s https://kaolin.hoodi.arkiv.network/rpc \
  -H "content-type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"eth_sendRawTransaction",
    "params":["'"$SIGNED_TX"'"]
  }'

Polling for the Receipt

curl -s https://kaolin.hoodi.arkiv.network/rpc \
  -H "content-type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"eth_getTransactionReceipt",
    "params":["'"$TX_HASH"'"]
  }'

The receipt’s logs contain the entity keys for each operation.

Batch Operations

All five operation types can be combined in a single transaction:

[
  [[1296000, "application/json", "{\"name\":\"Entity A\"}", [["type","alpha"]], []]],
  [["0xabc...", "application/json", 2592000, "{\"name\":\"Updated B\"}", [["type","beta"]], []]],
  ["0xdef..."],
  [["0x123...", 3888000]],
  [["0x456...", "0x789..."]]
]

Transaction Receipt Log Order

When parsing logs from a batch transaction, events are emitted in this order:

Creates
Deletes
Updates