# 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](https://www.ietf.org/rfc/rfc2119.txt).

> 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]        | …      |

### 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 |

### Encoding/ [ARC-4](https://dev.algorand.co/arc-standards/arc-0004) 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  |

## Backwards Compatibility

All backwards compatibility must be done with an Adapter.

## Reference Implementation

- See [StoreKit](https://storekit.io/)

## Security Considerations

- This does not account for private data.

## Copyright

Copyright and related rights waived via [CCO](https://creativecommons.org/publicdomain/zero/1.0/).