schema.ipldsch

# EntryChunk captures a chunk in a chain of entries that collectively contain the multihashes
# advertised by an Advertisement.
type EntryChunk struct {
    # Entries represent the list of multihashes in this chunk.
    Entries [Bytes]
    # Next is an optional link to the next entry chunk. 
    Next optional Link
}

# ExtendedProvider specifies an additional set of providers where the ad entries are available from
type ExtendedProvider   struct {
    # Providers is an additional list of providers where the ad entries are available from
    Providers [Provider]
    # Override defines mechanics for extending chain-level extended providers in the following way:
    # * If Override is set on an ExtendedProvider entry on an advertisement with a ContextID, it indicates that any specified chain-level 
    #   set of providers should not be returned for that context ID. Providers will be returned Instead.
    # * If Override is not set on an entry for an advertisement with a ContextID, it will be combined as a union with any chain-level ExtendedProviders (Addresses, Metadata).
    # * If Override is set on ExtendedProvider for an advertisement without a ContextID, the entry is invalid and should be ignored.
    Override Bool
} 

# Provider contains details of a peer where ad entries are available from
type Provider struct {
    # ID is a peer ID of the Provider 
    ID String
    # Addresses is a list of multiaddresses of the Provider
    Addresses [String]
    # Metadata captures contextual information about how to retrieve the advertised content.
    Metadata Bytes
    # Signature is created by each provider with their corresponding private key
    # * The full advertisement object is serialized, with all instances of Signature replaced with an empty array of bytes.
    # * This serialization is then hashed, and the hash is then signed.
    # * The Provider from the encapsulating advertisement must be present in the Providers of the ExtendedProvider object, 
    #   and must sign in this way as well. It may omit Metadata and Addresses if they match the values already set at the encapsulating advertisement. However, Signature must be present.
    Signature Bytes
}

# Advertisement signals availability of content to the indexer nodes in form of a chunked list of 
# multihashes, where to retrieve them from, and over protocol they are retrievable.
type Advertisement struct {
    # PreviousID is an optional link to the previous advertisement.
    PreviousID optional Link
    # Provider is the peer ID of the host that provides this advertisement.
    Provider String
    # Addresses is the list of multiaddrs as strings from which the advertised content is retrievable.
    Addresses [String]
    # Signature is the signature of this advertisement.
    Signature Bytes
    # Entries is a link to a data structure that contains the advertised multihashes.
    # The data structure can either be:
    #  * an interlinked chain of EntryChunk nodes, or 
    #  * an IPLD HAMT ADL, where the keys in the map represent the multihashes and the values are 
    #    simply set to true.
    #
    # See: 
    #  * https://ipld.io/specs/advanced-data-layouts/hamt/spec
    #  * https://ipld.io/specs/advanced-data-layouts/hamt/spec/#use-as-a-set
    Entries Link
    # ContextID is the unique identifier for the collection of advertised multihashes.
    # If a Provider listing is written with no ContextID and IsRm=false, peers from ExtendedProvider 
    # will be returned for all advertisements published by the publisher.
    ContextID Bytes
    # Metadata captures contextual information about how to retrieve the advertised content.
    Metadata Bytes
    # IsRm specifies whether this advertisement represents the content are no longer retrievalbe fom the provider.
    IsRm Bool
    # ExtendedProvider might optionally specify a set of providers where the ad entries are available from. 
    # See: https://github.com/ipni/storetheindex/blob/main/doc/ingest.md#extendedprovider
    ExtendedProvider optional ExtendedProvider
}