Key Name Specification

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:

key	value
o_alice	APZK5I5UAURBDSGFBEHYK3B235CDGYGXG6BAGC34ZHGDPQOJTBM5OSG6IE
o_bob	BX2RWWE77PA7JNNIPWUBQYX44LDHDE6EBRFEPLJUOMBNLT4ATQ3SA7UGEQ
o_metadata.rp	algorand.co

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

key	value
o_index	2
o_mime	text/plain
o_blobs[0]	…
o_blobs[1]	…

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

key	value
o_${path.to.value}	data for super long key

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/ARC-4 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

key	value
o_APZK5I5UAURBDSGFBEHYK3B235CDGYGXG6BAGC34ZHGDPQOJTBM5OSG6IE	bytes

This is only illustrative of the current encoding practices, a mapping of ARC-4 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