LBRY Claim Metadata Schema

The schema defines the structure of the data that is stored in claims in the LBRY blockchain. It has several goals:

  • Extensibility. The schema could grow to encompass thousands of fields for dozens of types of content. It should be easy to modify the schema while maintaining backward compatibility. Blockchain data is permanent and cannot be migrated, so any selected data structure will have to be maintained forever.
  • Compactness. Blockchain space is expensive. Data should be stored as compactly as possible.
  • Cross-language Interop. These definitions will be used by many projects written in different languages.

Claim

A Claim is the top level schema for everything that is published to the blockchain.

message Claim {
    enum Version {
        UNKNOWN_VERSION = 0;
        _0_0_1 = 1;
    }
    required Version version = 1;

    enum ClaimType {
        UNKNOWN_CLAIM_TYPE = 0;
        streamType = 1;
        certificateType = 2;
    }
    required ClaimType claimType = 2;

    optional Stream stream = 3;
    optional Certificate certificate = 4;
    optional Signature publisherSignature = 5;
}

Content

Stream

All content claims have a Stream field, which includes the content-specific information (e.g. a description of the content, instructions for downloading the content, etc).

message Stream {
    enum Version {
        UNKNOWN_VERSION = 0;
        _0_0_1 = 1;
    }
    required Version version = 1;

    required Metadata metadata = 2;
    required Source source = 3;
}

Metadata

Metadata provides information about a piece of content, such as the title, description, and price.

message Metadata {
    enum Version {
        UNKNOWN_VERSION = 0;
        _0_0_1 = 1;
        _0_0_2 = 2;
        _0_0_3 = 3;
        _0_1_0 = 4;
    }
    required Version version = 1;

    enum Language {
        UNKNOWN_LANGUAGE = 0;
        en = 1;
    }
    required Language language = 2;

    required string title = 3;
    required string description = 4;
    required string author = 5;
    required string license = 6;
    required bool nsfw = 7;

    optional Fee fee = 8;

    optional string thumbnail = 9;
    optional string preview = 10;
    optional string licenseUrl = 11;
}

Fee

A Fee defines the prices for accessing a piece of content.

message Fee {
    enum Version {
        UNKNOWN_VERSION = 0;
        _0_0_1 = 1;
    }
    required Version version = 1;

    enum Currency {
        UNKNOWN_CURRENCY = 0;
        LBC = 1;
        BTC = 2;
        USD = 3;
    }
    required Currency currency = 2;

    required bytes address = 3;
    required float amount = 4;
}

Source

A Source contains information on how to download a stream. Only the LBRY data network is supported at the moment, but other sources may be added in the future.

message Source {
    enum Version {
        UNKNOWN_VERSION = 0;
        _0_0_1 = 1;
    }
    required Version version = 1;

    enum SourceTypes {
        UNKNOWN_SOURCE_TYPE = 0;
        lbry_sd_hash = 1;
    }
    required SourceTypes sourceType = 2;

    required bytes source = 3;
    required string contentType = 4;
}

Channels

Channels are the identity mechanism in LBRY. They are constructed out of Certificates and Signatures. Both utilize a KeyType:

enum KeyType {
    UNKNOWN_PUBLIC_KEY_TYPE = 0;
    NIST256p = 1;
    NIST384p = 2;
    SECP256k1 = 3;
}

Certificate

Creating a channel involves making a certificateType claim. This claim contains the public key for a channel. It must include a Certificate field:

message Certificate {
    enum Version {
        UNKNOWN_VERSION = 0;
        _0_0_1 = 1;
    }
    required Version version = 1;

    required KeyType keyType = 2;
    required bytes publicKey = 4;
}

Signature

Publishing a claim to a channel simply means that the claim is signed using the private key for a channel. This is done by including a Signature field in a Claim:

message Signature {
    enum Version {
        UNKNOWN_VERSION = 0;
        _0_0_1 = 1;
    }
    required Version version = 1;

    required KeyType signatureType = 2;
    required bytes signature = 3;
    required bytes certificateId = 4;
}

This website is in beta and under heavy development.
All information should be considered incomplete and possibly incorrect and things may not work as expected.



Please do not share or link this site publicly while this message is here. This website is open source and you can contribute to it on Github.