Confederacy Lookup Availability Protocol (CLAP)

Ty Everett (ty@projectbabbage.com)

Abstract

We specify the Confederacy Lookup Availability Protocol (CLAP), a protocol for advertising the availability of BRC-24 lookup services on overlay network nodes. CLAP is an extension of BRC-23 that focuses on advertising the availability of lookup services instead of topics. By enabling the discovery of lookup services provided by various network operators, CLAP facilitates efficient and decentralized access to relevant data. This document details the format for CLAP tokens, their propagation across the network, and the process of using them to find and connect with hosts offering lookup services.

Motivation

While BRC-23 provides a mechanism for resolving which topics are hosted on which nodes, there is a need for a similar protocol that advertises the availability of lookup services. The underlying motivations for BRC-25 are similar to those for BRC-23, with the primary goal of facilitating efficient access to and discovery of lookup services in a decentralized manner.

Specification

In a similar manner to BRC-23 CHIP, we specify the various components of the CLAP architecture:

CLAP Token Format

CLAP tokens are registered on the Bitcoin SV blockchain as single-satoshi BRC-48 outputs representing lookup service advertisements by Confederacy network operators. The token fields are ordered as follows:

Field
Meaning

Field 1

The string CLAP, denoting a Confederacy Lookup Availability Protocol advertisement.

Field 2

The BRC-31 identity key of the advertiser creating the token.

Field 3

The internet domain name of the HTTPS server hosting the network node.

Field 4

The service name, represented by a BRC-24 provider ID.

Token Creation and Submission

The advertiser creates a transaction output containing the token and submits it to known nodes, including their own. The BRC-48 locking key must be linked to the advertiser's BRC-31 identity key using the BRC-42 and BRC-43 methodologies.

The advertiser follows these steps to derive the BRC-48 locking key, compute the signature, and advertise the transaction to all known nodes:

  1. Deriving the BRC-48 Locking Key:

    • Use the advertiser's BRC-31 identity key as the sender private key in the BRC-42 key derivation, with the "anyone" public key (1 by G) as the counterparty.

    • Compute the invoice number using the BRC-43 methodology with security level 2, protocol ID CLAP, and key ID of 1.

    • Derive the signing private key from your identity key using the computed invoice number.

  2. Computing the Signature:

    • Use the derived private key to compute the BRC-48 signature over the token fields.

  3. Advertising the Transaction:

    • Create a transaction output containing the CLAP token.

    • Submit the transaction to all known nodes, including the advertiser's own node.

There is no need to advertise that nodes host CLAP itself. It is assumed that all nodes which understand and receive CLAP advertisements intrinsically host CLAP, as they are already participating in the CLAP network and processing the advertisements.

Token Validation and Admission

Nodes accepting CLAP tokens must validate the identity key's link to the signature-producing key before admitting the output. Invalid tokens must be rejected. The following steps detail the token validation process:

  • Step 1: Extract token fields. Upon receiving a CLAP token, the node should first extract the four fields as defined in the token format. These fields include the CLAP identifier, the advertiser's BRC-31 identity key, the domain name of the HTTPS server hosting the network node, and the service name represented by a BRC-24 provider ID.

  • Step 2: Verify the CLAP identifier. Check that the first field of the token is the string CLAP. If this condition is not met, reject the token as invalid.

  • Step 3: Verify the BRC-48 locking key. Utilize the advertiser's claimed BRC-31 identity key as the sender public key in the BRC-42 key derivation process, with the "anyone" private key (1) as the recipient. Compute the invoice number using the BRC-43 methodology with security level 2, protocol ID CLAP, and key ID of 1. Derive the public key from the advertiser's identity key using this invoice number. Ensure that the computed key matches the BRC-48 locking key. If the keys are not linkable, reject the token as invalid.

  • Step 4: Verify the BRC-48 signature. Check the signature over the token fields by using the derived public key from the previous step. Ensure that the signature is valid and corresponds to the fields provided in the token.

  • Step 5: Admit the token. If all previous steps have been successfully completed and the token is deemed valid, admit the token into the CLAP topic.

CLAP Lookup Service

The CLAP BRC-24 lookup service enables network users to access and query for CLAP advertisement UTXOs in a standardized way. By facilitating access to these UTXOs, users can discover other nodes that may have the lookup services they need, enhancing connectivity across the UTXO-based overlay network.

Provider Name

The specified provider name for the lookup service is CLAP. This standardized name allows implementations to easily recognize and interact with the service.

Query Processing

The lookup service processes queries as JSON objects containing "service" and "advertiser" keys. These keys are used in an AND stipulation to filter the results based on the provided values. The service searches the UTXOs for matches that satisfy both conditions (if present) and returns the corresponding results.

Query Fields and AND Stipulation

The query fields are as follows:

Field
Meaning

service

The BRC-24 provider ID of the lookup service, used to filter UTXOs based on the desired service.

advertiser

The BRC-31 identity key of the advertiser, used to filter UTXOs based on the specific advertiser.

The AND stipulation operates by requiring both service and advertiser conditions to be satisfied for a UTXO to be included in the result set. If only one key is provided, the lookup service will return UTXOs matching that single condition. If both keys are present, the service will only return UTXOs that match both the specified service and advertiser.

Query Examples

Example 1: Query with only "service"

{
  "service": "example_service"
}

In this example, the lookup service will return all UTXOs with the specified "example_service", regardless of the advertiser.

Example 2: Query with only "advertiser"

{
  "advertiser": "02bc91718b3572462a471de6193f357b6e85ee0f8636cb87db456cb1590f913bea"
}

Here, the service will return all UTXOs from the specified advertiser, regardless of the service.

Example 3: Query with both "service" and "advertiser"

{
  "service": "example_service",
  "advertiser": "02bc91718b3572462a471de6193f357b6e85ee0f8636cb87db456cb1590f913bea"
}

In this case, the lookup service will return UTXOs that match both the specified service and advertiser, providing more precise results.

Discovering Nodes Hosting a Lookup Service of Interest

This section details the process for an overlay network user to discover nodes hosting a particular lookup service they are interested in. The user will follow these steps to locate relevant nodes and make a query from the service:

  • Query the CLAP Lookup Service. The user initiates the process by querying the CLAP lookup service through a known node. The query contains the desired "service" key, and optionally the "advertiser" key if the user wants to find a specific advertiser hosting the service. The CLAP lookup service returns a list of UTXOs with corresponding CLAP tokens containing relevant domain names and identity keys of advertisers.

  • Contacting Servers and Performing Queries. Upon receiving the list of UTXOs, the user extracts the domain names and identity keys of the relevant nodes. The user then contacts each server at their respective domain via the BRC-24 protocol, making use of the service to run a query and receive the results.

  • Verifying Identity Key during Lookup. During the UTXO lookup process, the user verifies that the identity key of the advertiser matches the key used by the server for authentication. This step ensures that the server is the intended recipient and maintains the integrity of the lookup process.

By following these steps, an overlay network user can discover nodes hosting a specific lookup service of interest and securely engage with them to learn about the current state of various overlays. This process enhances the connectivity and efficiency of UTXO-based overlay networks.

Implementation

There are no known implementations of this specification at this time. The specification will be updated when an implementation is published.

PreviousOverlay Network Lookup ServicesNextUniversal Hash Resolution Protocol

Last updated