Skip to content

Latest commit

 

History

History
147 lines (103 loc) · 4.95 KB

1.md

File metadata and controls

147 lines (103 loc) · 4.95 KB

Basal Entry Version 1

Abstract

This document defines the specification for Basal Entry Version 1.

Table of Contents

Introduction

The Basal Entry format is used to append updates to an immutable log. They are encoded using dag-cbor and make use of binary data type provided by cbor.

Entry Format

A Basal Entry is a data structure, encoded using dag-cbor [spec] and containing the following fields:

  • auth (CID)

    • The creator of the entry. This is a CID pointing to the identity used to sign the entry.

  • sig (bytes)

    • The signature from signing the data field or its hash with the identity referenced by the auth field.

  • data (bytes)

    • The encapsulated entry data.
see cbor encoding specification and tag 42
  {
    auth: tag 42
    sig: type 2
    data: tag 2
  }

Encapsulated Entry Data

  • v (uint64)

    • Denotes the version of the entry. In this case equal to 1 to denote version 1.

  • tag (CID)

    • The tag field is used to associate the entry with a specific log/database.

  • ops (any[])

    • The ops field contains the useful data being appended to the log like a database operation.

  • next (CID[])

    • The next field is an array of entry CID not yet referenced by other known entries in the log, also know as log heads. Used for ordering traversal.

  • refs (CID[])

    • The refs field is an array of entry CID, like the next field, but they reference entries farther back in the log. Used for replication, not used for ordering.
  {
    v: type 0
    tag: type 2
    clock: type 0
    ops: type 4<type 5>
    next: type 4<tag 42>
    refs: type 4<tag 42>
  }

Example Entry:

  • signed entry
  {
    auth: CID(bafyreicl6ujc6ncfktctxxroxognfn7d2fqavvrryoc2lv6m4i6hpbkfti),
    sig: Uint8Array(70) [
       48,  68,   2,  32,  98, 244, 207, 200, 184, 243, 204,
        1,  40,  59,  37, 234, 179, 238, 178, 149,  97,  75,
      176, 250, 168, 189,  32, 240,  38, 193,  72, 122, 230,
       99,  18,  17,   2,  32, 124, 228,  21, 189, 116,  35,
      182, 109, 105,  83,  56, 193, 113,  34, 233,  55,  37,
      159, 119, 209, 232, 100, 148, 211,  20, 100,  54, 240,
      149, 159, 204, 198
    ],
    data: Uint8Array(70) [
      165,  97, 118,   3,  99, 116,  97, 103, 216,  42,  88,
       37,   0,   1, 113,  18,  32, 243,  64,  63, 229, 158,
       73, 246,  56,  86, 242,  31, 109, 173,  83,  27, 158,
      163,  37,  69, 192, 100, 224, 218, 199, 181,  95, 207,
      153,  21, 242,  16, 236, 100, 110, 101, 120, 116, 128,
      100, 114, 101, 102, 115, 128, 103, 112,  97, 121, 108,
      111,  97, 100, 246
    ]
  }
  • entry data
  {
    v: 3,
    tag: CID(bafyreihtia76lhsj6y4fn4q7nwwvgg46umsulqde4dnmpnk7z6mrl4qq5q)
    ops: [],
    next: [],
    refs: []
  }

The length of an encoded entry with empty ops and reference fields is ~200 bytes.

Fields that can change in length include the clock, ops, and reference fields. Each CID added to a reference field would increase the length of the entry by ~40 bytes.

Signature Creation and Verification

The sig field must be the byte output of the DSA used to sign the binary format of data field's CID with the identity referenced by the auth field. The identity specifies the DSA and keys being used to create and verify the sig field.

The auth field must reference data that can be used to verify the validity of the entry signature and data. In most cases this is an [identity] with a public key.

The data field must be the dag-cbor encoded entry data.

Reference Fields

There are two reference fields inside a Basal Entry, next and refs. These fields exist inside the entry data as arrays of CID.

The next field must include the CID for every entry not yet referenced by other entries in the replica. These entries to be referenced are sometimes called heads or log heads and should be the newest entries added.

The refs field may include any entry CID that is not already references in the next field and

Validity Constraints

  • The entry passes the ipld schema of the entry format being used.
  • The entry tag matches the manifest tag of the database the entry will be added to.
  • The entry auth field resolves to a valid identity of the format specified by the manifest.
  • The sig field is a valid ECDSA signature created with:
    • signing key: resolved identity's signing key.
    • signed data: data field CID as a byte array.

TODO: ADD IPLD SCHEMA, ADD OPTIONS