# Confederacy Lookup Availability Protocol (CLAP) Ty Everett () ## Abstract We specify the Confederacy Lookup Availability Protocol (CLAP), a protocol for advertising the availability of [BRC-24](/overlays/0024.md) lookup services on overlay network nodes. CLAP is an extension of [BRC-23](/overlays/0023.md) 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](/overlays/0023.md) 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](/overlays/0023.md), 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](/overlays/0023.md) CHIP, we specify the various components of the CLAP architecture: ### Status Note BRC-25 is historical. Current interoperable lookup-service discovery in `bsv-blockchain/ts-sdk` is specified by [BRC-88](/overlays/0088.md) SLAP advertisements, not CLAP advertisements. New implementations should use: * `SLAP` PushDrop advertisement tokens, * host base URLs rather than bare domain names, * lookup service names following [BRC-87](/overlays/0087.md), normally beginning with `ls_`, * BRC-100 PushDrop locking under protocol `[2, "Service Lookup Availability"]`, key ID `1`, counterparty `self`, * and BRC-24 lookup service `ls_slap` for resolving hosts that provide a service. The `CLAP` identifier, `CLAP` topic, BRC-48 signature-linking process, and provider-style lookup naming below are retained only for historical context. ### CLAP Token Format CLAP tokens are registered on the Bitcoin SV blockchain as single-satoshi [BRC-48](/scripts/0048.md) 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](/peer-to-peer/0031.md) 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](/overlays/0024.md) 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](/scripts/0048.md) locking key **must be linked** to the advertiser's [BRC-31](/peer-to-peer/0031.md) identity key using the [BRC-42](/key-derivation/0042.md) and [BRC-43](/key-derivation/0043.md) methodologies. The advertiser follows these steps to derive the [BRC-48](/scripts/0048.md) locking key, compute the signature, and advertise the transaction to all known nodes: 1. Deriving the [BRC-48](/scripts/0048.md) Locking Key: * Use the advertiser's [BRC-31](/peer-to-peer/0031.md) identity key as the sender private key in the [BRC-42](/key-derivation/0042.md) key derivation, with the "anyone" public key (`1` by `G`) as the counterparty. * Compute the invoice number using the [BRC-43](/key-derivation/0043.md) 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](/scripts/0048.md) 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](/peer-to-peer/0031.md) identity key, the domain name of the HTTPS server hosting the network node, and the service name represented by a [BRC-24](/overlays/0024.md) 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**](/scripts/0048.md) **locking key.** Utilize the advertiser's claimed [BRC-31](/peer-to-peer/0031.md) identity key as the sender public key in the [BRC-42](/key-derivation/0042.md) key derivation process, with the "anyone" private key (`1`) as the recipient. Compute the invoice number using the [BRC-43](/key-derivation/0043.md) 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](/scripts/0048.md) locking key. If the keys are not linkable, reject the token as invalid. * **Step 4: Verify the** [**BRC-48**](/scripts/0048.md) **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](/overlays/0024.md) 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](/overlays/0024.md) provider ID of the lookup service, used to filter UTXOs based on the desired service. | | `advertiser` | The [BRC-31](/peer-to-peer/0031.md) 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" ```json { "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" ```json { "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" ```json { "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](/overlays/0024.md) 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://bsv.brc.dev/overlays/0025.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.