Encoding and Decoding

The core API is exposed in the eris module. This allows you to encode an decode content.

The version of the specification implemented is set in eris.spec_version:

eris.spec_version()

Returns the version of the ERIS specification implemented

Store

Before we can encode or decode content, we need to be able to store and retrieve blocks frome somewhere. This functionality is provided by stores.

eris.Store()

Stores blocks of encoded content

Stores can be bindings to in-memory structures, databases or network protocols. See the section on storage and transport layers.

Basic Stores

Two basic stores are provided as part of the core API.

eris.NullStore()	A store that does not store anything.
eris.DictStore()	A in-memory store using a Python dict

Encoding Content

Content can be encoding using an eris.Encoder.

eris.Encoder(convergence_secret[, store, ...])

Encode content to a store

Content must be provided as Python bytes:

import eris
import asyncio

async def main():
    encoder = eris.Encoder(eris.null_convergence_secret(), block_size = 1024)

    await encoder.write(b'Hello world!')

    read_capability = await encoder.close()

    print(read_capability)

asyncio.run(main())

Multiple bytes can be added to the encoded content incrementally by calling encoder.write multiple times. This allows encoding of content larger than memory

Note that a convergence secret must be provided (see <http://purl.org/eris#name-convergence-secret>). It is safe to use 32 bytes of random byte (e.g. secrets.token_bytes(32)). If you are aware of the attacks against convergent encryption and want deterministic identifiers you may use the null convergence secret (32 bytes of zeroes), which is provided in eris.null_covergence_secret:

eris.null_convergence_secret()

Returns a null convergence secret (32 bytes of zero).

Decoding Content

Content can be decoded using an eris.Decoder.

eris.Decoder(store, read_capability)

Read ERIS encoded content.

To decode some previously encoded content:

import eris
import asyncio

async def main():

    # create a store
    store = eris.DictStore()

    # encode content
    encoder = eris.Encoder(eris.null_convergence_secret(), store, block_size = 1024)
    await encoder.write(b'Hello world!')
    read_capability = await encoder.close()

    # decode content
    decoder = eris.Decoder(store, read_capability)
    decoded = await decoder.readall()

    print(decoded)

asyncio.run(main())

Decoders allow efficient random-access to content as specific positions using the seek and read methods.