BRC-102 Protocol

An Automated Liquidity Protocol for BRC-100 Assets

Time: Jan. 9 2024

Creator: Mikael.btc

Twitter: https://twitter.com/MikaelBTC

This article defines the BRC-102 protocol.

1. Summary

BRC-102 is an automated liquidity protocol for BRC-100 assets, that defines an automated market making method based on "constant product formula" (x*y=k) for a pair of tokens based on BRC-100 protocol stack.

2. Abstract

The BRC-102 protocol inherits from the BRC-100 protocol, and is the first extension protocol for applications in the BRC-100 protocol stack. The BRC-102 protocol defines an automated market making method based on "constant product formula" (x*y=k) for a pair of tokens based on BRC-100 protocol stack. There are three roles in the protocol: liquidity provider, trader, and liquidity pool. The liquidity provider is responsible for providing the two tokens of the pair to the liquidity pool. These two tokens can be tokens based on any protocol in the BRC-100 Protocol Stack such as BRC-100, BRC-102, BRC-103, etc. Traders can exchange one token of the pair for another in the liquidity pool. The liquidity pool is based on the AMM algorithm of "constant product formula" (x*y=k), which will automatically provide liquidity to traders and is implemented by the BRC-100 indexers. Through the cooperation of the three roles, BRC-102 can realize a completely decentralized, trustless, self-custody, censorship-resistant, and permissionless token exchange on Bitcoin Layer 1.

3. Concepts

There are seven important concepts in the BRC-102 protocol: Inscriptions, Swap, Liquidity Pool, Returns, Fees & Rewards, Block Hole Address and Decimals. These seven concepts cover the core algorithm of this protocol. The application deployed based on BRC-102 protocol is called: Liquidity Pool. Swapping tokens, adding/removing liquidity are all interacting with the Liquidity Pool.

3.1 Inscriptions

Inscriptions are the basis of the BRC-100 protocol stack, and of course the basis of BRC-102. Users inscribe inscriptions with UTXO and parameters, then transfer the inscriptions to transfer the UTXO and notify the indexer to compute the states.

The burn2/burn3 computing logic has four steps:

Inscribe the inscription with UTXO and parameters.
Transfer the inscription to the deployer of the "to" application.
Indexers compute UTXO and states changes.
Users mint the "mint2"/"mint3" related states to UTXO.

The mint2/mint3 computing logic has two steps:

Inscribe the inscription with UTXO and parameters.
Indexers compute UTXO and states changes.

The entire process is completed on Bitcoin Layer 1. The transfer of burn2/burn3 inscriptions does not actually transfer the assets to the receiver, but only completes the conversion of UTXO to state. In this protocol, the transfer of user assets must meet the preset rules, and no custody of user assets is required.

3.2 Swap

Swap refers to using one token based on the BRC-100 Protocol Stack to exchange for another in the Liquidity Pool. In the BRC-102 protocol, there is no need to wait for the matching of buyers and sellers like the orderbook marketplace does, the trading can be completed immediately. The trading process is completed in the liquidity pool, which will be introduced in the next section. The liquidity pool is based on the Automated Market Maker (AMM) algorithm of "constant product formula" (x*y=k), which automatically provides liquidity to trading users and completes trades immediately. Traders can use op: burn3 and cop: sw inscriptions to exchange one token for another.

1. The trader inscribes the inscription with op: burn3 and cop: sw. The inscription contains the tokens to be paid, as well as restrictions: the received token minimum amount: ext.aom (Amount Out Min) and the deadline timestamp: ext.dl (deadline).

2. The trader transfers the inscription to the deployer of the liquidity pool, to swap tokens. The receiver cannot mint the mint3able balance, only the deployer does not actually hold the user's assets and cannot transfer the assets. It is only used to complete the conversion from UTXO to state.

3. If the inscription is not sent to the deployer, the computing fails, and the paid token will enter the trader's state rsb3 and the mint3able balance of the receiving address. The receiver cannot mint the mint3able balance, only the trader can use cop: r3 and op: mint3 defined in the BRC-100 protocol to re-mint the tokens to himself to complete the conversion from state to UTXO. At the same time, the following steps will no longer be performed.

4. If the current block timestamp is greater than the set deadline timestamp: ext.dl, the computing fails.

5. Compute the token amount that the trader can receive based on the "constant product formula" (x*y=k) algorithm. Taking into account the black hole percentage, tax percentage and fees, the constant formula should be: ${x}_{0\cdot }{y}_{0}=({x}_{0}+{x}_{in}-{x}_{in}\cdot {p}_{tbhp}-{x}_{in}\cdot {p}_{ttp}-{x}_{in}\cdot {p}_{lpfp}-{x}_{in}\cdot {p}_{sfp})\cdot ({y}_{0}-{y}_{out})$ , then the received token amount should be: ${y}_{out}={y}_{0}-\frac {{x}_{0}\cdot {y}_{0}} {{x}_{0}+{x}_{in}-{x}_{in}\cdot {p}_{tbhp}-{x}_{in}\cdot {p}_{ttp}-{x}_{in}\cdot {p}_{lpfp}-{x}_{in}\cdot {p}_{sfp}}$ . If the amount is less than the minimum amount set by the ext.aom, the computing fails, otherwise the computing is successful, and the received token enters state sb3.

6. If the computing is successful, the black hole and tax parts will enter state sb3. fees have two parts: one part is allocated to the liquidity provider, and the other part is allocated to the preset address, which are determined by the parent application attributes ext.lpfp and ext.sfp respectively. The ext.lpfp part will change the corresponding state reserve0 or reserve1, which means to be allocated to all liquidity providers, and ext.sfp will enter the state sb3.

7. If the computing is successful, the state reserve0 or reserve1 corresponding to ${x}_{in}$ need to increase ${x}_{in}-{x}_{in}\cdot {p}_{tbhp}-{x}_{in}\cdot {p}_{ttp}-{x}_{in}\cdot {p}_{sfp}$ , the state reserve0 or reserve1 corresponding to ${y}_{out}$ need to decrease ${y}_{out}$ .

8. If the computing fails, the paid token enters state sb3.

9. Regardless of whether the computing succeeds or fails, the paid token will enter the mint3able balance of the deployer. The deployer cannot mint the mint3able balance, only the users who meet the conditions can mint them from the state sb3.

10. Finally, if the computing is successful, the trader can use cop: w3 and op: mint3 defined in the BRC-100 protocol to mint the received token to himself from the state sb3, to complete the conversion from state to UTXO.

3.3 Liquidity Pool (LP)

The application deployed by BRC-102 protocol is called Liquidity Pool, which is a trading venue for a pair of BRC-100 tokens of the Pool. The trading is based on the Automated Market Maker (AMM) algorithm of "constant product formula" (x*y=k). The protocol has two computing operations to manage liquidity: add liquidity and remove liquidity. After adding liquidity, the token will enter the mint3able balance of the Pool's deployer. No one can manipulate the token at will. The token must be converted to user's states through the protocol's preset rules when removing liquidity or swapping tokens. Then the user can mint3 the states to himself to complete the conversion from state to UTXO. The whole process is completely decentralized and there is no third-party custody of user assets.

3.3.1 Add Liquidity

The user adds two tokens to the Pool by op: burn3 and cop: al inscription, then receives LP Token as the liquidity certification.

1. The liquidity provider inscribes the inscription with op: burn3 and cop: al. The inscription contains the two Tokens to be added to the Pool, as well as the restrictions: the deposited minimum amount of the two Tokens: ext.a0m (Amount0 Min) and ext.a1m (Amount1 Min), and the deadline timestamp: ext.dl (deadline).

2. The liquidity provider transfers the inscription to the deployer of the liquidity pool to add liquidity. The deployer does not actually hold the user's assets and cannot transfer the assets. It is only used to complete the conversion from UTXO to state.

3. If the inscription is not sent to the deployer, the computing fails, and the sent tokens will enter the liquidity provider's state rsb3 and the mint3able balance of the receiving address. The receiver cannot mint the mint3able balance, only the liquidity provider can use cop: r3 and op: mint3 defined in the BRC-100 protocol to re-mint the tokens to himself to complete the conversion from state to UTXO. At the same time, the following steps will no longer be performed.

4. If the current block timestamp is greater than the set deadline timestamp: ext.dl, the computing fails.

5. Compute the actual tokens amounts that should be added to the Pool. If there are no tokens in the Pool, both sent tokens will be added to the Pool. Otherwise, compute ${y}_{deposited\_ optimal}=\frac {{Reserve}_{y}} {{Reserve}_{x}}\cdot {x}_{deposited\_ desired}$ , if ${y}_{deposited\_ optimal}\leq {y}_{deposited\_ desired}$ , the actual deposited tokens amounts ( ${x}_{deposited}$ and ${y}_{deposited}$ ) should be ${x}_{deposited\_ desired}$ and ${y}_{deposited\_ optimal}$ . Otherwise, they should be ${x}_{deposited\_ optimal}=\frac {{Reserve}_{x}} {{Reserve}_{y}}\cdot {y}_{deposited\_ desired}$ and ${y}_{deposited\_ desired}$ . If any of the actual deposited tokens amounts is less than the set minimum amount or greater than the amount of UTXO, the computing fails, otherwise the computing succeeds. Among them, ${x}_{deposited\_ desired}$ and ${y}_{deposited\_ desired}$ are the tokens amounts in the inscription, ${x}_{deposited}$ and ${y}_{deposited}$ represent the actual tokens amounts that are added to the pool.

6. If the computing fails, the sent tokens enter state sb3.

7. Regardless of whether the computing succeeds or fails, the sent tokens will enter the mint3able balance of the deployer. The deployer cannot mint the mint3able balance, only the users who meet the conditions can mint them from the state sb3.

8. If the computing is successful, the user can receive LP Token as the certification for adding liquidity, that is, changing the state sb2. The amount computing rules are divided into two types. If the Pool does not have any token: ${s}_{minted}=\sqrt {{x}_{deposited}\cdot {y}_{deposited}}-{1}^{-15}$ , otherwise, ${s}_{minted}=min(\frac {{x}_{deposited}} {{x}_{starting}}\cdot {s}_{starting},\frac {{y}_{deposited}} {{y}_{starting}}\cdot {s}_{starting})$ . When adding initial liquidity, 1e-15 LP Token will be sent to the black hole address, that is, the state sb2 of the black hole address will be changed, to prevent extreme situations from occurring.

9. If the computing is successful, the state reserve0 and reserve1 need to increase ${x}_{deposited}$ and ${y}_{deposited}$ .

10. If the computing is successful, the user can use cop: w2 and op: mint2 defined in the BRC-100 protocol to mint the received LP token to himself from the state sb2, to complete the conversion from state to UTXO.

11. Finally, if any of the two tokens is left after the computing, it will enter the state sb3 to return to the user. The user can re-mint through cop: w3 and op: mint3 defined in the BRC-100 protocol, to himself to complete the conversion from state to UTXO.

3.3.2 Remove Liquidity

The user uses the op: burn2 and cop: rl inscription to burn the liquidity certification: LP Token to the Pool to remove the liquidity, and receive the two Tokens with corresponding proportions.

1. The liquidity provider inscribes the inscription with op: burn2 and cop: rl. The inscription contains the liquidity certification: LP Token, as well as restrictions: the withdrawn minimum amount of two Tokens: ext.a0m (Amount0 Min) and ext.a1m (Amount1 Min), and the deadline timestamp: ext.dl (deadline).

2. The liquidity provider transfers the inscription to the deployer of the liquidity pool to remove liquidity. The deployer does not actually hold the user's assets and cannot transfer the assets. It is only used to complete the conversion from UTXO to state.

3. If the inscription is not sent to the deployer, the computing fails, and the sent LP Token will enter the liquidity provider's state rsb2. The liquidity provider can use cop: r2 and op: mint2 defined in the BRC-100 protocol to re-mint the tokens to himself to complete the conversion from state to UTXO. At the same time, the following steps will no longer be performed.

4. If the current block timestamp is greater than the set deadline timestamp: ext.dl, the computing fails.

5. Compute the two withdrawn tokens amounts after removing liquidity according to the formula: ${x}_{withdrawn}=\frac {{s}_{burned}} {{s}_{starting}}\cdot {x}_{starting}$ , ${y}_{withdrawn}=\frac {{s}_{burned}} {{s}_{starting}}\cdot {y}_{starting}$ , if any of computed amounts is less than the set withdrawn minimum amount, the computing fails, otherwise the computing is successful and the state sb3 will be changed.

6. If the computing fails, the sent tokens enter state sb2.

7. If the computing is successful, the state reserve0 and reserve1 need to decrease ${x}_{withdrawn}$ and ${y}_{withdrawn}$ .

8. If the computing is successful, the user can use cop: w3 and op: mint3 defined in the BRC-100 protocol to mint the two tokens after removing liquidity to himself from the state sb3, to complete the conversion from state to UTXO.

3.4 Returns

Since the BRC-102 protocol is based on UTXO inscriptions, the tokens amounts in the inscription are fixed, there will be some cases where tokens are left, and the left tokens will be returned to the user in the form of returns, that is, changing the state sb3, such as adding liquidity, there is a high probability that one token will be returned to the user.

3.5 Fees & Rewards

In the BRC-102 protocol, two fees will be charged when the users swap tokens: Liquidity Provider Fee and Service Fee. These two fees are set through the properties of the parent application: ext.lpfp and ext.sfp respectively. ext.lpfp is added directly to reserve0 or reserve1, which serves as rewards for all LP providers. The other ext.sfp is added to the state sb3 of the receiving address ext.sfr, and is rewarded to the application provider.

3.6 Black Hole Address

The attribute: tbhp (trading block hole percentage) is defined in the BRC-100 protocol, which represents the percentage allocated to the block hole when the tokens are traded on the AMM DEX. The block hole is represented in this protocol as an address that no one can control, mainnet: 1BitcoinEaterAddressDontSendf59kuE, testnet/signet: mxxD8soCEyzP3ZJReqKUPsTYC7ZCfeLsvo. And the allocation to the black hole represents the sb2, sb3 and other states allocated to the address.

3.7 Decimals

This protocol may have accuracy issues when computing the states. In order to ensure that all BRC-100 indexers can obtain completely consistent results after computing, the computing needs to be carried out according to the following rules.

Every operator without special meaning are processed as decimals is 30.
The operators of tokens, even in the middle of the formula, needs to be consistent with the token decimals, such as the computing of trading black hole, trading tax, liquidity provider fee, service fee.
The decimals of the state need to be consistent with the decimals of the corresponding token, for example reserve0 decimals should equal to the ticker0 decimals.
The states without corresponding tokens, need to be processed as decimals is 18.
If the computing result exceeds decimals, the excess part needs to be discarded.
The decimals of 4 attributes: tbhp, ttp, ext.lpfp, and ext.sfp are 18. If exceeded, the deployment will fail.

4. Parameters

The parameters are defined in the protocol and do not need to be set when deploying the application.

Parameter

Value

Description

extends

BRC-100

Inherit from which protocol

upgradeFrom

Which protocols can be upgraded to this protocol

openAsChild

Yes

Can be deployed by anyone as a child application

onlyChild

Yes

Can only be deployed as child application

stoppable

Can be stopped

5. Operations

This chapter defines the operations and operators of BRC-102 protocol. Since BRC-102 inherits from BRC-100, all operations and operators in BRC-100 will be inherited, and new operations and operators are not allowed to be added. However, in order to express more semantics, the reserved extension attribute: ext will be defined in detail.

5.1 Deploy

For the BRC-102 protocol, all attributes of the BRC-100 protocol will be inherited. Since BRC-102 can be deployed as a child application by anyone using op: deploy, some special attributes require permission restrictions and can only be set by the application owner. Therefore, these attributes can only be set in the ext of the parent application, not in the ext of the child application. These attributes include ext.lpfp (Liquidity Provider Fee Percentage), ext.sfp (Service Fee Percentage), ext.sfr (Service Fee Receiver). At the same time, these attributes in the parent application can be upgraded. If the first two attributes are not set, the corresponding default values will be used. If ext.sfr is not set, the service fee receiver will be the owner of the current application. If the owner is changed, the service fee receiver will also be changed. Please refer the ext details of the parent application in the following table.

Attribute

Description

Required?

Upgradable?

lpfp

Liquidity Provider Fee Percentage, default: 0.002

Yes

sfp

Service Fee Percentage, default: 0.001

Yes

sfr

Service Fee Receiver, to Owner if not set

Yes

For example, deploy the parent application: amm_dex based on the BRC-100 protocol.

{
  "p": "BRC-100",
  "op": "deploy",
  "tick": "amm_dex",
  "max": "21000000",
  "lim": "1000",
  "ext": {
    "lpfp": "0.0025",
    "sfp": "0.0005",
    "sfr": "bc1pdkyv4vp507vrvj4x3h4pmlj2jrz235vmex9cz7flkg8mvra2jmzq50ay7c"
  }
}

For example, deploy the child application: amm_dex:bridge@btc_brc100 based on the BRC-102 protocol of parent application: amm_dex.

{
  "p": "BRC-102",
  "op": "deploy",
  "tick": "amm_dex:lp_bridge@btc_brc100",
  "dec": "18",
  "mma": "0",
  "moma": "0",
  "b3t": ["bridge:btc","BRC100"],
  "ids": "true",
  "dvl": "1000000001",
  "gtl": "10000001"
}

5.1.1 Deployment Constraints

This chapter is used to describe the constraints when the protocol is deployed to the Bitcoin network through inscriptions. Applications can only be deployed successfully if they meet these constraints. In addition to the basic format constraints, the BRC-102 protocol also needs to meet some other logic constraints for successful deployment, as shown in the following table. A special one is "b3t" attribute, which represents the two tickers of the two tokens in the current LP, and cannot be duplicated in all child applications based on BRC-102 of the current child LP application’s parent application. For example, if "b3t": ["bridge:btc","BRC100"] already exists, the child application based on BRC-102 deployment of "b3t": ["bridge:btc","BRC100"] or ["BRC100","bridge:btc" ] will fail.

Attribute

Constraint

max

should not be set

amt

should not be set

lim

should not be set

dec

should be "18"

mma

should be "0"

moma

should be "0"

adms

should not be set

tbhp

should not be set

ttp

should not be set

b3t

should be 2 tickers, not exist among all the BRC-102 child applications of the parent application

ids

should be "true"

dvl

should be greater than 1,000,000,000

gtl

should be greater than 10,000,000

ext

lpfp, sfp, sfr should not be set

6. Computing Operations

This chapter defines the extension cop of the BRC-102 protocol. Of course, since the BRC-102 protocol inherits from BRC-100, all the cops defined in BRC-100 are still valid in the BRC-102 protocol. BRC-102 adds 3 new cops: cop: al (Add Liquidity), rl (Remove Liquidity), sw (Swap), and in the ext attribute corresponding to the cop, adds the dl attribute to represents the deadline timestamp of the computing (in seconds), which will be introduced in detail below.

6.1 Swap: sw

As described in the Swap of Concepts chapter, cop: sw and op: burn3 are used together to complete the exchange of tokens. ext.aom (Amount Out Min) represents the minimum amount of tokens to be exchanged, and ext.dl (deadline) represents the deadline timestamp of this computing (in seconds). If the received token amount is less than the minimum amount: ext.aom, or the confirmation time on the chain is greater than ext.dl, the computing will fail. After the token swapping is successfully, the states: sb3, reserve0, reserve1 will be updated.

{
  "p": "BRC-103",
  "op": "burn3",
  "tick": "bridge:btc",
  "amt": "0.1",
  "cop": "sw",
  "to": "amm_dex:lp_bridge@btc_brc100",
  "ext":{
    "aom": "0.8",
    "dl": "1735689599"
  }
}

After the Swap is successful, the user can use cop: w3 and op: mint3 defined in the BRC-100 protocol to mint the received token to himself from the state sb3.

{
  "p": "BRC-100",
  "op": "mint3",
  "tick": "BRC100",
  "amt": "0.9",
  "cop": "w3",
  "from": "amm_dex:lp_bridge@btc_brc100"
}

6.2 Add Liquidity: al

As described in the Add Liquidity of Concepts chapter, cop: al and op: burn3 are used together to add liquidity. ext.a0m (Amount0 Min) and ext.a1m (Amount1 Min) respectively represent the deposited token minimum amount with index 0 (state ticker0) and index 1 (state ticker1) in the "b3t" array, and cannot be greater than the corresponding token amount in the UTXO. ext.dl (deadline) represents the deadline timestamp of this computing (in seconds). If any of the deposited amount of two tokens is less than the minimum amount, or the confirmation time on the chain is greater than ext.dl, the computing will fail. After successfully adding liquidity, the states: sb3, reserve0, reserve1, sb2 will be updated.

{
  "p": "BRC-100",
  "op": "burn3",
  "tick": "BRC100",
  "amt": "10",
  "cop": "al",
  "to": "amm_dex:lp_bridge@btc_brc100",
  "ts":[{
      "p": "BRC-103",
      "tick": "bridge:btc",
      "amt": "1"
  }],
  "ext":{
    "a0m": "9",
    "a1m": "0.9",
    "dl": "1735689599"
  }
}

After adding liquidity successfully, the user can use cop: w2 and op: mint2 defined in the BRC-100 protocol to mint the application token (LP Token) as the liquidity certification from state sb2.

{
  "p": "BRC-102",
  "op": "mint2",
  "tick": "amm_dex:lp_bridge@btc_brc100",
  "amt": "3.1",
  "cop": "w2",
  "from": "amm_dex:lp_bridge@btc_brc100"
}

6.3 Remove Liquidity: rl

As described in the Remove Liquidity of Concepts chapter, cop: rl and op: burn3 are used together to remove liquidity. ext.a0m (Amount0 Min) and ext.a1m (Amount1 Min) respectively represent the withdrawn token minimum amount with index 0 (state ticker0) and index 1 (state ticker1) in the "b3t" array. ext.dl (deadline) represents the deadline timestamp of this computing (in seconds). If any of the withdrawn amount of two tokens is less than the minimum amount, or the confirmation time on the chain is greater than ext.dl, the computing will fail. After successfully removing liquidity, the states: sb3, reserve0, reserve1 will be updated.

{
  "p": "BRC-102",
  "op": "burn2",
  "tick": "amm_dex:lp_bridge@btc_brc100",
  "amt": "2",
  "cop": "rl",
  "to": "amm_dex:lp_bridge@btc_brc100",
  "ext":{
    "a0m": "0.5",
    "a1m": "0.05",
    "dl": "1735689599"
  }
}

After the liquidity is successfully removed, the user can use cop: w3 and op: mint3 defined in the BRC-100 protocol to mint the two withdrawn tokens from state sb3 to himself.

{
  "p": "BRC-103",
  "op": "mint3",
  "tick": "bridge:btc",
  "amt": "0.6",
  "cop": "w3",
  "from": "amm_dex:lp_bridge@btc_brc100"
}

7. States

This chapter is used to describe the states in the BRC-102 protocol. Similarly, BRC-102 inherits all the states from the BRC-100 protocol, and the following 5 new states will be added:

ticker0, represents the token with index 0 in the "b3t" array of the current application/pool.
ticker1, represents the token with index 1 in the "b3t" array of the current application/pool.
reserve0, represents the ticker0 amount deposited in the current application/pool.
reserve1, represents the ticker1 amount deposited in the current application/pool.
supply, represents the LP token supply of the current application/pool, equals to "the LP token amount obtained by adding liquidity" - "the LP token amount burned by removing liquidity".

8. Reference

[1] Uniswap v2 Core, https://docs.uniswap.org/whitepaper.pdf

[2] [brc-20] Introduction to brc-20, https://l1f.discourse.group/t/brc-20-introduction-to-brc-20/72

[3] [BRC-100] Introduction to BRC-100, https://l1f.discourse.group/t/brc-100-introduction-to-brc-100/79

[4] BRC-100 Protocol, https://docs.brc100.org/

Last updated 8 months ago