ARC-87: Key Name Specification

A system for addressable values

Abstract

Adopt a standard key name specification for complex data.

This defines key names that can be used to represent JSON, Blobs, or other structures that do not fit neatly into the state

Motivation

This pattern has emerged over time as a way to circumvent constraints with state storage. This seeks to codify the practice into a shared definition which can be leveraged as a primitive in the ecosystem.

This greatly simplifies the cross-cutting concerns when integrating with complex structures by directly addressing values on-chain.

Specification

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC-2119.

All bullet points are in reference to Key Names

• SHOULD be prefixed with o_ (for discovery/indexing)
• MUST separate nested object keys with .
• MUST index collections with [N]
• SHALL be escaped by starting with ${ and ending in }

Rationale

Multiple variants of this pattern create downstream cycles which could be avoided.

JSON/Objects

Given the following object:

{
  "alice": "APZK5I5UAURBDSGFBEHYK3B235CDGYGXG6BAGC34ZHGDPQOJTBM5OSG6IE",
  "bob": "BX2RWWE77PA7JNNIPWUBQYX44LDHDE6EBRFEPLJUOMBNLT4ATQ3SA7UGEQ",
  "metadata": {
    "rp": "algorand.co"
  }
}

Represents the following Key/Value pairs:

Blob/File

Assuming the blob is greater than the state storage, chunking is required and can be represented in an object

{
  "index": 2,
  "mime": "text/plain",
  "blobs": [
    "...",
    "..."
  ]
}

Would produce the following keys

This is only illustrative of the value size constraints, a dedicated specification would be more robust for bespoke Objects. This is out of scope for this key name specification.

Templatization

Assuming the key names are greater than 64 bytes, mapping of the names to values is required.

{
  "this is a really long key that for some reason is extra long even though it probably doesn't need to be this long but idk maybe someone has a key this long": "data for super long key"
}

Would produce the following keys

This is only illustrative of the key size constraints, a dedicated specification would be more robust for applying templates. This is out of scope for this key name specification.

Encoding/ARC4 Containers

Assuming the values are encoded, further processing is required with knowledge of the types

{
  "APZK5I5UAURBDSGFBEHYK3B235CDGYGXG6BAGC34ZHGDPQOJTBM5OSG6IE": [0,1,2,3,...]
}

Given the value type

class PackedValue extends Struct<{
    a: uint64
    b: uint64
}> {}

Would be represented as the following object

{
  "APZK5I5UAURBDSGFBEHYK3B235CDGYGXG6BAGC34ZHGDPQOJTBM5OSG6IE": {
    "a": 1234,
    "b": 1234
  }
}

And would produce the following keys

This is only illustrative of the current encoding practices, a mapping of ARC4 Containers to key paths could be done at a future date. This is out of scope for this key name specification.

Backwards Compatibility

All backwards compatibility must be done with an Adapter.

Reference Implementation

• See StoreKit

Security Considerations

• This does not account for private data

Copyright

Copyright and related rights waived via CCO.

Citation

Please cite this document as:

Michael Feher, "ARC-87: Key Name Specification [DRAFT]," Algorand Requests for Comments, no. 87, July 2025. [Online serial]. Available: https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0087.md.