Civia social data structures

Purpose

The Civia social data structures are designed to support

  • the definition and operation of souls, voices and their associations with blockchains

  • offchain soken issuance and storage

  • organizing social relationship data for quick lookup, retrieval, and tracking of the relationship state changes

  • generating proof of existence and proof of relations for onchain verifications

Soul, Voice and Sokens

  • A soul represents an entity's unique identity offchain and across multiple EVM compatible or L2 blockchains. The entity can be a person, an organization or any generic entity capable of actions in a relationship. A soul is associated with an AA account on each chain.

  • Voices are expressed by souls in the form of messages, postings, publications etc. Each voice is associated with it's originating soul and has its unique id. Voice is implemented as a variant of soul.

  • Relationships between souls, voices, often social in nature, are represented by sokens

  • A soken is issued by a soul, bound to a receiver's soul or voice, and are not transferable

  • Sokens represent social relationships and social interaction such as "like", "follow", and can encode a soul's nickname.

Offchain storage and in-memory data

  • All soul, voices and sokens are created and stored offchain, in databases or decentralized storage such as Arweave. The data is read-only once created.

  • Apps or centralized servers can build the in-memory representation of the relationships network in the form of Verkel trees, with verkle trees it is efficient to track relationship states and generate proofs of relationships.

  • Offchain apps or onchain contracts can verify the relationship proofs for application specific purposes

Verkle tries

Soul trie

  • Soul trie is used to map AA account addresses to soul identities

  • It is easy to lookup from AA account to soul identity

  • Reverse lookup (from soul to AA account) can be done with offchain storage or in-memory databases

  • The (AA account, soul) mapping implemented by the soul trie can be verified with proofs generated from the soul trie

  • Soul trie supports update and revocation of the (AA account, soul) mappings

Leaf data

  • Index (32 bytes)

    • last 30 bytes of AA contract address (if an address is less then 30 bytes, it is padded at the end to 30 bytes)

    • chainId (2 bytes)

  • Value

    • soul id (or voice id, 32 bytes)

      • the AA contract address from which the soul is first created

      • for voice id, this field is the hash of the voice data

    • creation timestamp (4 bytes)

    • signature (EIP-4337 compliant account signatures)

      • When binding a new AA account to an existing soul, signatures are required from both the controlling address of an AA account already bound to the soul and the controlling address of the new AA account

  • A soul is first created when an AA account signs the soul data offchain

  • A voice is created when the AA account of the originating soul signs the voice

  • The soul value in a leaf node can be updated or deleted because the index is independent of the leaf value

Soken trie

  • Soken trie is constructed to store relationship information represented by sokens, including relationships between

    • soul->soul: e.g. like, follow, belong, nickname

    • soul->voice: e.g. soul issues voices, soul likes voice

Leaf data

  • Index: for each leaf the index is the hash of the leaf value

  • Value

    • Soken id: 32 bytes

      • Anyone can register a new soken id with the Civia Soken Service

      • Soken id is unique

    • Issuer: 32 bytes soul id

    • Owner: 32 bytes soul id or voice id

    • Value: 32 bytes integer value of the soken

    • Metadata: 32 bytes

    • Signatures: 72 bytes, signed by the controlling address of the AA account of the soul initiating the action

    • Timestamp: 4 bytes

  • Soken issuance must include the signature of one of the AA accounts associated with the issuer

    • Wallet bound to any of the issuer's AA accounts of any chain can make the signature

    • A soken can be revoked, when it is unbound from the issuing soul.

Soken revocation trie

  • Soken data are read only once issued. The soken revocation trie records and validates information on soken revocations. It uses the same index as the soken trie. The value of the revocation trie leaf indicates if the soken in the corresponding soken trie leaf under the same index is revoked.

  • Soken revocations can be proven and verified just like in the soken trie

Verifications

  • Once souls, voices, sokens are built into the leaf data of verkle tries, proof of existence and proof of relations can be constructed, and efficient verifications can be performed onchain or offchain.

  • To track state updates of the relationship map, only the roots of the verkle tries need to be stored onchain

  • High frequency trie root updates as results of relationship data updates can be batched when persisting onchain to save gas cost.

Last updated