Splash Protocol Core

https://github.com/splashprotocol/splash-core
Admin
Splash Protocol provides Cardano smart contract implementations for a CFMM DEX, including pool,...
Tokens:4,166
Snippets:32
Trust Score:-
License:CC0-1.0
Update:1 year ago
Show doc for...
Tokens:
Raw
### Set up direnv for automatic environment loading

Source: https://github.com/splashprotocol/splash-core/blob/main/README.md

Instructions to configure direnv for automatic environment loading using Nix flakes, ensuring a consistent development setup when entering project directories. This command should be run in the respective project directory (e.g., onchain or offchain).

```bash
$ echo "use flake .#onchain" > .envrc 
# ^ in the onchain directory of the project (and in the same way for the offchain project)
$ direnv allow
```

--------------------------------

### Build and Test Haskell Project in Nix Shell Environment

Source: https://github.com/splashprotocol/splash-core/blob/main/CONTRIBUTING.md

Enter the Nix shell environment using `nix-shell`, then proceed to build and test the Haskell project by running `cabal build` and `cabal test` commands respectively. This verifies the project's integrity within the Nix-managed dependencies.

```Shell
nix-shell
cabal build
cabal test
```

--------------------------------

### Enter Nix development environment for project parts

Source: https://github.com/splashprotocol/splash-core/blob/main/README.md

Commands to enter specific Nix development environments for either the onchain (Plutarch) or tooling parts of the project. These commands provide all necessary dependencies and tools for development.

```bash
nix develop .#onchain
```

```bash
nix develop .#tooling
```

--------------------------------

### Build onchain project with Nix

Source: https://github.com/splashprotocol/splash-core/blob/main/README.md

Command to build the onchain part of the project using Nix. This specifically targets the 'plutarch-validators' library, ensuring all onchain components are compiled.

```bash
nix build .#"plutarch-validators:lib:plutarch-validators"
```

--------------------------------

### Build and Test Haskell Project in VSCode Dev Container

Source: https://github.com/splashprotocol/splash-core/blob/main/CONTRIBUTING.md

After rebuilding the VSCode development container image, navigate into the environment and execute `cabal build` and `cabal test` to compile and verify the Haskell project. Ensure that the Haskell Language Server (HLS) is functioning correctly.

```Shell
cabal build
cabal test
```

--------------------------------

### Limit Order Lifecycle Transitions

Source: https://github.com/splashprotocol/splash-core/blob/main/docs/LimitOrder.md

Describes the three possible state transitions for a Limit Order: Cancellation, Partial fill, and Terminal fill, outlining their effects on the order's state and the conditions under which they occur.

```APIDOC
Limit Order Transitions:
1. Cancellation: An order can be cancelled at any time by an authorized party.
2. Partial fill: Part of In_t is removed in exchange for Out. Structure of the order is preserved: address, immutable datum fields.
3. Terminal fill: Remainder of In_t is removed in exchange for Out. An output to configured redeemer address is created.
```

--------------------------------

### Splash AMM Swap Order Implementation

Source: https://github.com/splashprotocol/splash-core/blob/main/docs/stableswap/SplashStablePool.md

Describes the swap order mechanism, implemented as a uniform Splash AMM-order within the protocol.

```APIDOC
Swap order is implemented as uniform Splash AMM-order.
```

--------------------------------

### Limit Order UTxO State Variables and Immutable Parameters

Source: https://github.com/splashprotocol/splash-core/blob/main/docs/LimitOrder.md

Defines the data structure held within each Limit Order UTxO, including mutable state variables that track remaining amounts and immutable configuration parameters that dictate execution behavior.

```APIDOC
Limit Order UTxO Datum State Variables:
- In_t: Remaining amount of tradable input (in input asset units)
- Lovelace_f: Remaining amount of execution fee (in Lovelace units)

Limit Order UTxO Immutable Parameters:
- C: budget per execution step (amount that executor can use to cover TX fee at each execution step)
- P: minimal exchange rate (Output/Input)
```

--------------------------------

### Deposit Operation Token Inputs

Source: https://github.com/splashprotocol/splash-core/blob/main/docs/stableswap/SplashStablePool.md

Describes the tradable assets (X, Y, Z) that are provided as input for a deposit operation. The amounts are arbitrary but must be sufficient to cover any associated fees.

```APIDOC
Tokens for Deposit operation (n=3 tradable assets):
- Name: X
  Description: Base asset
  Amount: Arbitrary, but at least to pay the fees
- Name: Y
  Description: First quote asset
  Amount: Arbitrary, but at least to pay the fees
- Name: Z
  Description: Second quote asset
  Amount: Arbitrary, but at least to pay the fees
```

--------------------------------

### Rearranged Invariant Equation for Output Token Calculation

Source: https://github.com/splashprotocol/splash-core/blob/main/docs/stableswap/SplashStablePool.md

The invariant equation rearranged into a quadratic form f(y) = 0, specifically for calculating the output token amount 'y' when other asset amounts are known. Here, b = S + D/(Ann), c = D^(n+1)/(n^n P Ann), S = sum of x_i for i not equal to j, and P = product of x_i for i not equal to j.

```APIDOC
\begin{equation}
f(y) = y^2 + (b - D)y - c = 0,
\end{equation}
```

--------------------------------

### Newton's Iteration for Output Token Calculation

Source: https://github.com/splashprotocol/splash-core/blob/main/docs/stableswap/SplashStablePool.md

The specific Newton-Raphson iteration formula derived for calculating the output token amount 'y' based on the rearranged invariant equation f(y) = 0. This formula is iterated until convergence to determine the final output amount.

```APIDOC
\begin{equation}
y_{n + 1} = y_n - \frac{y_n^2 + (b - D) y - c}{2 y_n + b - D} = \frac{y_n^2 + c}{2 y_n + b - D}
\end{equation}
```

--------------------------------

### Redeem Uniform Operation Token Inputs

Source: https://github.com/splashprotocol/splash-core/blob/main/docs/stableswap/SplashStablePool.md

Describes the liquidity token (LP) as the input for a uniform redeem operation, indicating that an arbitrary amount of LP tokens can be provided.

```APIDOC
Tokens for Redeem Uniform operation:
- Name: LP
  Description: Base asset
  Amount: Arbitrary
```

--------------------------------

### Obtain Correct Nix Hash for Plutus Apps

Source: https://github.com/splashprotocol/splash-core/blob/main/CONTRIBUTING.md

To resolve incorrect SHA256 hashes for Plutus applications in `nix/pkgs/haskell/haskell.nix`, intentionally introduce an error by changing a digit in the hash. Running `nix-shell` will then output the correct hash value, which can be used to update the configuration.

```Shell
nix-shell
```

--------------------------------

### Limit Order Valid Exchange Constraints

Source: https://github.com/splashprotocol/splash-core/blob/main/docs/LimitOrder.md

Specifies the mathematical constraints that a valid exchange must satisfy. These rules ensure correct asset exchange rates, proper handling of Lovelace as input/output, and accurate fee management for different transaction scenarios.

```APIDOC
Valid Exchange Constraints:
{
  ΔOut ≥ -ΔIn_t * P if Out ≠ Lovelace
  ΔOut + ΔLovelace_f - C ≥ -ΔIn_t * P if Out = Lovelace
  ΔLovelace_f ≤ (ΔIn_t * Lovelace_f^0) / In_t_0
  ΔIn ≥ ΔIn_t + ΔIn_f - C if In = Lovelace
  ΔIn ≥ ΔIn_t if In ≠ Lovelace
  ΔLovelace ≥ ΔIn_f - C if In ≠ Lovelace and Out ≠ Lovelace
}
Where:
ΔOut = Out_1 - Out_0
ΔIn = In_1 - In_0
ΔLovelace = Lovelace_1 - Lovelace_0
ΔIn_t = In_t_1 - In_t_0
ΔLovelace_f = Lovelace_f_1 - Lovelace_f_0
```

--------------------------------

### Newton-Raphson Method General Formula

Source: https://github.com/splashprotocol/splash-core/blob/main/docs/stableswap/SplashStablePool.md

The iterative formula for the Newton-Raphson method used to find the roots of an equation f(x) = 0. This method is chosen for its efficiency and precision in approximating solutions to complex equations.

```APIDOC
\begin{equation}
x_{n + 1} = x_n - \frac{f(x_n)}{f'(x_n)}
\end{equation}
```

--------------------------------

### Redeem Operation Token Inputs

Source: https://github.com/splashprotocol/splash-core/blob/main/docs/stableswap/SplashStablePool.md

Describes the liquidity token (LP) as the primary input for a redeem operation, indicating that an arbitrary amount of LP tokens can be provided.

```APIDOC
Tokens for Redeem operation:
- Name: LP
  Description: Liquidity token
  Amount: Arbitrary
```

--------------------------------

### Newton's Iteration for Invariant Parameter D Calculation

Source: https://github.com/splashprotocol/splash-core/blob/main/docs/stableswap/SplashStablePool.md

The specific Newton-Raphson iteration formula derived for calculating the invariant parameter D, based on the function f(D) = 0. Here, f'(D) = (n + 1) D_P / D + (Ann - 1), where D_P = D^(n+1) / (n^n * product x_i).

```APIDOC
\begin{equation}
D_{n + 1} = D_n - \frac{f(D_n)}{f'(D_n)} = \frac{(Ann S + n D_P) D_n}{(Ann - 1) D_n+(n + 1) D_P}
\end{equation}
```

--------------------------------

### StablePool-proxy DAO Contract Functionality

Source: https://github.com/splashprotocol/splash-core/blob/main/docs/stableswap/SplashStablePool.md

Explains the role of the StablePool-proxy DAO contract as a separate entity for verifying non-AMM actions, allowing protocol logic extensions without impacting the main pool contract. It relies on script and Splash DAO voting confirmations.

```APIDOC
The StablePool-proxy DAO contract is a separate contract that verifies the correctness of non-AMM actions (AMM actions are: `deposit/redeem/swap`). It allows to add different logic to the protocol without significantly affecting the main pool contract.
The pool will only verify that the corresponding script and Splash DAO voting confirmed action.
```

--------------------------------

### Redeem Operation Data Fields

Source: https://github.com/splashprotocol/splash-core/blob/main/docs/stableswap/SplashStablePool.md

Specifies the data fields required for a redeem operation, including the target pool identifier, the redeemer's public key, a list of expected assets, their minimum expected balances, and the minimum expected change in LP tokens.

```APIDOC
Data fields for Redeem operation:
- Field: pool_nft
  Type: Asset
  Description: Identifier of the target pool
- Field: redeemer
  Type: VerificationKeyHash
  Description: Redeemer public key
- Field: expected_assets
  Type: List<Asset>
  Description: Expected assets
- Field: min_expected_received_assets_balances
  Type: List<Int>
  Description: Minimum expected balances of expected tokens
- Field: min_expected_lp_change
  Type: Int
  Description: Minimum expected balances of LP tokens
```

--------------------------------

### Stable3Pool Data Structure Reference

Source: https://github.com/splashprotocol/splash-core/blob/main/docs/stableswap/SplashStablePool.md

This section details the immutable and mutable data fields associated with a Stable3Pool instance in the Splash Protocol. It describes each field's purpose, data type, and whether its value can change after pool creation, providing a comprehensive reference for pool configuration and state.

```APIDOC
Stable3Pool Data Fields:
- pool_nft:
    Type: Asset
    Description: Identifier of the pool
    State: Immutable
- n:
    Type: Int
    Description: Number of tradable assets in the pool
    State: Immutable
- tradable_assets:
    Type: List<Asset>
    Description: Identifiers of the tradable assets
    State: Immutable
- tradable_tokens_multipliers:
    Type: List<Int>
    Description: Precision multipliers for calculations, i.e. precision / decimals. Precision must be fixed as maximum value of tradable tokens decimals
    State: Immutable
- lp_token:
    Type: Asset
    Description: Identifier of the liquidity token asset
    State: Immutable
- lp_fee_is_editable:
    Type: Bool
    Description: Flag if liquidity provider fee is editable
    State: Immutable
- ampl_coeff:
    Type: Integer
    Description: StableSwap invariant amplification coefficient
    State: Mutable
- lp_fee_num:
    Type: Integer
    Description: Numerator of the liquidity provider fee
    State: Mutable
- protocol_fee_num:
    Type: Integer
    Description: Numerator of the protocol fee share
    State: Mutable
- dao_stabe_proxy_witness:
    Type: List<ScriptHash>
    Description: Information about the DAO script, which audits the correctness of the "DAO-actions" with stable pool
    State: Mutable
- treasury_address:
    Type: ScriptKeyHash
    Description: Treasury address
    State: Mutable
- protocol_fees:
    Type: List<Int>
    Description: Collected (and currently available) protocol fees in the tradable assets native units
    State: Mutable
- inv:
    Type: Integer
    Description: Actual value of the pool's invariant
    State: Mutable
```

--------------------------------

### StableSwap Invariant Equation

Source: https://github.com/splashprotocol/splash-core/blob/main/docs/stableswap/SplashStablePool.md

The fundamental invariant equation for the effective stablecoin exchange in a StableSwap pool, involving asset amounts (x_i), amplification factor (A), and number of assets (n). This equation forms the basis for numerical solutions when analytical methods are not possible.

```APIDOC
\begin{equation}
A n^n \sum x_i + D = D A n^n + \frac{D^{n + 1}}{n^n \prod x_i}
\end{equation}
```

--------------------------------

### Function for Calculating Invariant Parameter D

Source: https://github.com/splashprotocol/splash-core/blob/main/docs/stableswap/SplashStablePool.md

The polynomial function f(D) = 0 used to calculate the invariant parameter D, given all other parameters are constant. S represents the sum of all asset amounts (sum x_i).

```APIDOC
\begin{equation}
f(D) = \frac{D^{n + 1}}{n^n \prod x_i} + (Ann - 1) D - Ann S = 0
\end{equation}
```

--------------------------------

### Deposit Operation Data Fields

Source: https://github.com/splashprotocol/splash-core/blob/main/docs/stableswap/SplashStablePool.md

Specifies the required data fields for initiating a deposit operation into a StableSwap pool, including identifiers for the target pool, the redeemer, and the minimum expected amount of liquidity tokens to be received.

```APIDOC
Data fields for Deposit operation:
- Field: pool_nft
  Type: Asset
  Description: Identifier of the target pool
- Field: redeemer
  Type: VerificationKeyHash
  Description: Redeemer public key
- Field: min_expected_lp_amount
  Type: Int
  Description: Minimum expected amount of liquidity tokens
```

--------------------------------

### Proxy-DAO Contract Validation Rules

Source: https://github.com/splashprotocol/splash-core/blob/main/docs/stableswap/SplashStablePool.md

Outlines the validation requirements for the Proxy-DAO contract, ensuring preservation of pool invariant values and LP tokens, and validating specific non-AMM actions such as fee updates, address changes, and amplification coefficient adjustments.

```APIDOC
Proxy-DAO contract must validate that:
1. Pool invariant values are preserved;
2. `LP` tokens are preserved
3. Action is valid. The proxy-DAO contract ensures the correctness of the following actions:
   1. Update liquidity provider fee;
   2. Update protocol fee;
   3. Update treasury address;
   4. Update proxy DAO witness;
   5. Withdrawn protocol fees to distribute between Splash token holders;
   6. Update stake credential;
   7. Update amplification coefficient.
```

--------------------------------

### StableSwap Pool Token Definitions (n=3 Assets)

Source: https://github.com/splashprotocol/splash-core/blob/main/docs/stableswap/SplashStablePool.md

Defines the various tokens associated with a StableSwap pool configured for three tradable assets, including the unique pool NFT, base and quote assets, and the liquidity provider (LP) token.

```APIDOC
Tokens for n=3 tradable assets pool:
- Name: pool_NFT
  Description: NFT to identify the pool
  Amount: 1
- Name: X
  Description: Base asset token
  Amount: At least 1
- Name: Y
  Description: First quote asset token
  Amount: At least 1
- Name: Z
  Description: Second quote asset token
  Amount: At least 1
- Name: LP
  Description: Liquidity token of the X/Y/Z triplet
  Amount: Emission must be FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
```

--------------------------------

### Redeem Order Validator Rules

Source: https://github.com/splashprotocol/splash-core/blob/main/docs/stableswap/SplashStablePool.md

Outlines the validation criteria for a redeem order, ensuring that the order interacts with the correct pool, the redeemer receives the expected amounts of tokens, valid change, and that the redeemer's identity is valid.

```APIDOC
Redeem order validator must validate that:
1. Order interacts with the desired pool;
2. Expected amounts of expected tokens are received by redeemer;
3. Valid change is received by redeemer;
4. Redeemer is valid.
```

--------------------------------

### Redeem Uniform Operation Data Fields

Source: https://github.com/splashprotocol/splash-core/blob/main/docs/stableswap/SplashStablePool.md

Specifies the data fields for a 'Redeem Uniform' operation, which allows redemption in proportion to the pool's current balances without assuming a change in liquidity tokens. It includes the target pool identifier, redeemer, and minimum expected received balances of all tradable tokens.

```APIDOC
Data fields for Redeem Uniform operation:
- Field: pool_nft
  Type: Asset
  Description: Identifier of the target pool
- Field: redeemer
  Type: VerificationKeyHash
  Description: Redeemer public key
- Field: min_expected_received_assets_balances
  Type: List<Int>
  Description: Minimum expected balances of all tradable tokens
```

--------------------------------

### Deposit Order Validator Rules

Source: https://github.com/splashprotocol/splash-core/blob/main/docs/stableswap/SplashStablePool.md

Details the validation criteria for a deposit order, ensuring that the order interacts with the correct pool, the redeemer receives at least the expected amount of LP tokens, and the redeemer's identity is valid.

```APIDOC
Deposit order validator must validate that:
1. Order interacts with the desired pool;
2. Not less than expected LP token amount is received by redeemer;
3. Redeemer is valid.
```

--------------------------------

### Redeem Order Validator Rules

Source: https://github.com/splashprotocol/splash-core/blob/main/docs/stableswap/SplashStablePool.md

Defines the validation criteria for redeem orders within the Splash Protocol, ensuring interaction with the correct pool, accurate token reception, and valid redeemer.

```APIDOC
Redeem order validator must validate that:
1. Order interacts with the desired pool;
2. Expected amounts of all tokens are received by redeemer;
4. Redeemer is valid.
```

--------------------------------

### StableSwap Invariant Formula

Source: https://github.com/splashprotocol/splash-core/blob/main/docs/stableswap/SplashStablePool.md

The core mathematical invariant formula for the StableSwap AMM pool, combining constant sum and constant product principles. This formula is designed to provide deep liquidity and low price slippage for stable assets, especially around the equilibrium point where token prices are equal. The parameters include $x_i$ (balance of $i^{th}$ token), $D$ (total tokens at equilibrium), $A$ (amplification coefficient), and $n$ (number of tokens in the pool).

```math
\begin{equation}
A n^n \sum x_i + D = D A n^n + \frac{D^{n + 1}}{n^n \prod x_i}
\end{equation}
```

--------------------------------

### StableSwap Pool Validator Rules

Source: https://github.com/splashprotocol/splash-core/blob/main/docs/stableswap/SplashStablePool.md

Outlines the comprehensive validation rules that the pool validator must enforce to ensure the integrity and correct operation of the StableSwap pool, covering input validity, preservation of pool parameters, and action-specific checks for AMM and DAO operations.

```APIDOC
Pool validator must validate that:
1. Pool input is valid;
2. Pool address is preserved;
3. Pool NFT is preserved;
4. Immutable pool configuration parameters are preserved;
5. No more tokens are in the pool output;
6. Action is valid:
    a. In case of AMM action (Deposit/Redeem/Swap):
        i. Valid protocol fees;
        ii. Valid liquidity provider fees;
        iii. Valid tradable and liquidity token deltas;
        iv. Calculations were performed according to the StableSwap invariant with pool params.
    b. In case of DAO-actions:
        i. Action is confirmed by the proxy-StablePool DAO script;
        ii. Action is confirmed by the Splash DAO voting script.
```

--------------------------------

### Pool NFT Data Structure

Source: https://github.com/splashprotocol/splash-core/blob/main/docs/stableswap/SplashStablePool.md

Defines the `pool_nft` field used as an identifier for the target pool within the protocol.

```APIDOC
Field      | Type    | Description
------------|---------|-------------------------------
`pool_nft` | `Asset` | Identifier of the target pool
```
Tokens:
Raw