Confederacy Lookup Availability Protocol (CLAP)
Last updated
Was this helpful?
Last updated
Was this helpful?
Ty Everett (ty@projectbabbage.com)
We specify the Confederacy Lookup Availability Protocol (CLAP), a protocol for advertising the availability of lookup services on overlay network nodes. CLAP is an extension of 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.
While 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 , with the primary goal of facilitating efficient access to and discovery of lookup services in a decentralized manner.
In a similar manner to CHIP, we specify the various components of the CLAP architecture:
CLAP tokens are registered on the Bitcoin SV blockchain as single-satoshi outputs representing lookup service advertisements by Confederacy network operators. The token fields are ordered as follows:
Field 1
The string CLAP, denoting a Confederacy Lookup Availability Protocol advertisement.
Field 2
Field 3
The internet domain name of the HTTPS server hosting the network node.
Field 4
Derive the signing private key from your identity key using the computed invoice number.
Computing the Signature:
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.
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 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 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.
The specified provider name for the lookup service is CLAP. This standardized name allows implementations to easily recognize and interact with the service.
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.
The query fields are as follows:
service
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"
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"
Here, the service will return all UTXOs from the specified advertiser, regardless of the service.
Example 3: Query with both "service" and "advertiser"
In this case, the lookup service will return UTXOs that match both the specified service and advertiser, providing more precise results.
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.
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.
There are no known implementations of this specification at this time. The specification will be updated when an implementation is published.
The identity key of the advertiser creating the token.
The service name, represented by a provider ID.
The advertiser creates a transaction output containing the token and submits it to known nodes, including their own. The locking key must be linked to the advertiser's identity key using the and methodologies.
The advertiser follows these steps to derive the locking key, compute the signature, and advertise the transaction to all known nodes:
Deriving the Locking Key:
Use the advertiser's identity key as the sender private key in the key derivation, with the "anyone" public key (1 by G) as the counterparty.
Compute the invoice number using the methodology with security level 2, protocol ID CLAP, and key ID of 1.
Use the derived private key to compute the signature over the token fields.
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 identity key, the domain name of the HTTPS server hosting the network node, and the service name represented by a provider ID.
Step 3: Verify the locking key. Utilize the advertiser's claimed identity key as the sender public key in the key derivation process, with the "anyone" private key (1) as the recipient. Compute the invoice number using the 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 locking key. If the keys are not linkable, reject the token as invalid.
Step 4: Verify the 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.
The CLAP 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.
The provider ID of the lookup service, used to filter UTXOs based on the desired service.
The identity key of the advertiser, used to filter UTXOs based on the specific advertiser.
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 protocol, making use of the service to run a query and receive the results.