Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix typos #85

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ Let $P_i(w)$ be a decreasing, non-negative marginal price function for a token $

$$U = \int_{i_t}^{i_t + \Delta i} P_i(w) \ dw$$

Where $i_t$ is the current balance in the vault, $\Delta i$ is the change in balance caused by the user and $U$ is Units: A measure of the value change by the user. The equation can be used both ways, where a positive change implies a "swap in" and a negative change implies a "swap out". It is implies that when assets are swapped out, $U$ the sign is flipped from positive to negative.
Where $i_t$ is the current balance in the vault, $\Delta i$ is the change in balance caused by the user and $U$ is Units: A measure of the value change by the user. The equation can be used both ways, where a positive change implies a "swap in" and a negative change implies a "swap out". It implies that when assets are swapped out, $U$ the sign is flipped from positive to negative.

This implies that the full swap from a token $i$ to another token $j$ can be computed as:

Expand All @@ -49,7 +49,7 @@ Amplification: $P^\theta(w)= \frac{W_i}{(W_i \cdot w)^\theta} \cdot (1-\theta)$

**LocalSwap**: A combination of *sendAsset* and *receiveAsset* executed atomically, often on a single chain.

**Invariant**: A measure used to measure the vault value. Specific to the *invariant* measure, is that it is constant whenever a swap is completed. If a vault implements a swap fee, the measure increases as fees accumulate in the vault. The invariant is not invariant to deposits or withdrawals. The invariants can continously be examined if the number of emitted Units is kept track of. In the below equations, this is representated as $\sum U$.
**Invariant**: A measure used to measure the vault value. Specific to the *invariant* measure, is that it is constant whenever a swap is completed. If a vault implements a swap fee, the measure increases as fees accumulate in the vault. The invariant is not invariant to deposits or withdrawals. The invariants can continuously be examined if the number of emitted Units is kept track of. In the below equations, this is represented as $\sum U$.

## The AMM Equations

Expand Down
20 changes: 10 additions & 10 deletions evm/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ More specifically, the code structure is as follows:

## CatalystVaultCommon.sol

An `abstract` contract (i.e. a contract that is made to be overriden), which enforces the core structure of a Catalyst vault and implements features which are generic to any pricing curve. Among these are:
An `abstract` contract (i.e. a contract that is made to be overridden), which enforces the core structure of a Catalyst vault and implements features which are generic to any pricing curve. Among these are:

- Vault administration, including fees and vault connections management
- Cross chain swaps acknowledgement and timeout
Expand Down Expand Up @@ -57,7 +57,7 @@ Catalyst v1 implements 2 type of swaps, *Asset Swaps* and *Liquidity Swaps*. The

### Underwriting

Catalyst allows fast execution for swaps. This is done by allowing external underwriters to pre-execute a swap which is then settled ocne the swap is confirmed by the associated AMB (and relayed).
Catalyst allows fast execution for swaps. This is done by allowing external underwriters to pre-execute a swap which is then settled once the swap is confirmed by the associated AMB (and relayed).

Each swap is assigned a somewhat-uniquely identifier which contains the context for executing a swap. The computation for the identifier can be found below.

Expand Down Expand Up @@ -88,7 +88,7 @@ Each swap is assigned a somewhat-uniquely identifier which contains the context
}
```

When a swap is initially underwritten the identifier describes exactly how the swap is supposed to be executed. An underwriter collect the relevant swap execution context by decoding the AMB payload and then delivers it to the associated cross-chain interface `.underwrite`. The relevant swap is executed with the payment taken from the underwriter but escrowed on the vault.
When a swap is initially underwritten the identifier describes exactly how the swap is supposed to be executed. An underwriter collects the relevant swap execution context by decoding the AMB payload and then delivers it to the associated cross-chain interface `.underwrite`. The relevant swap is executed with the payment taken from the underwriter but escrowed on the vault.

Once the swap arrives, the identifier is calculated based on the payload and if an underwrite exists it is matched and the escrowed tokens are delivered to the underwriter.

Expand Down Expand Up @@ -116,13 +116,13 @@ To run the tests with Foundry:
forge test -vvv
```

Compiling the tests takes a significant amount of time but running the tests themselves is almost instant. The `-vvv` argument prints trace for any failling tests. Many tests are designed for fuzzing. By default, 100 fuzzes are made. To increase the number of runs add the argument `--fuzz-runs 1000`. If the number of runs is particularly high (>10000) some tests might fail with "rejected too many inputs".
Compiling the tests takes a significant amount of time but running the tests themselves is almost instant. The `-vvv` argument prints trace for any failing tests. Many tests are designed for fuzzing. By default, 100 fuzzes are made. To increase the number of runs add the argument `--fuzz-runs 1000`. If the number of runs is particularly high (>10000) some tests might fail with "rejected too many inputs".

## Coverage

The repository uses the Soldiity pipeline `--via-ir` to circumvent the *stack too deep* issue. The result is that when Foundry tries to re-compile the contracts without any optimisations it fails.

The forge argument `-ir-minimum` has to be used to compile the contracts using the `ir` representation. Note that this changes the mapping of source code to compiled code and some sections can be incorrectled marked as uncovered or covered.
The forge argument `-ir-minimum` has to be used to compile the contracts using the `ir` representation. Note that this changes the mapping of source code to compiled code and some sections can be incorrectly marked as uncovered or covered.

```
forge coverage --ir-minimum
Expand All @@ -134,7 +134,7 @@ This repository contains a helper script for deployment `script/DeployCatalyst.s

## Local Catalyst

Local Catalyst consists of Volatile and Amplified pools along with the Factory. To deploy Local Catalyst to another chain, add the chain config to `script/BaseMultiChainDeployer.s.sol`. For chains without EIP-1559 add them as a legacy chain.Then run `forge script DeployCatalyst --sig "deploy()" --broadcast` or `forge script DeployCatalyst --sig "deploy_legacy()" --legacy --broadcast` depending on if the chain added was with EIP-1559 support (non-legacy) or with (legacy). Some chains require running with `--slow`. If deployment fails, wait a few blocks and re-try.
Local Catalyst consists of Volatile and Amplified pools along with the Factory. To deploy Local Catalyst to another chain, add the chain config to `script/BaseMultiChainDeployer.s.sol`. For chains without EIP-1559 add them as a legacy chain. Then run `forge script DeployCatalyst --sig "deploy()" --broadcast` or `forge script DeployCatalyst --sig "deploy_legacy()" --legacy --broadcast` depending on if the chain added was with EIP-1559 support (non-legacy) or with (legacy). Some chains require running with `--slow`. If deployment fails, wait a few blocks and re-try.

## Cross-chain Catalyst

Expand Down Expand Up @@ -239,7 +239,7 @@ contract ExampleTest is TestCommon {
}
```

We are now ready to execute a localswpa. Lets swap 50 token0 for token1. A minimum output of 45 tokens is specified (if not fulfilled, the transaction will revert).
We are now ready to execute a localswap. Lets swap 50 token0 for token1. A minimum output of 45 tokens is specified (if not fulfilled, the transaction will revert).


```solidity
Expand Down Expand Up @@ -270,7 +270,7 @@ If you executed more swaps to test the minimum output, please undo those with `c

## Cross-Chain Vault Setup

Before being able of executing a cross-chain swap, we need to setup the associated cross-chain communication. We have already deployed a cross-chain interface but we havn't set it up yet. Lets do that:
Before being able of executing a cross-chain swap, we need to setup the associated cross-chain communication. We have already deployed a cross-chain interface but we haven't set it up yet. Lets do that:

```solidity
import { ICatalystV1Vault } from "../src/ICatalystV1Vault.sol";
Expand All @@ -285,7 +285,7 @@ contract ExampleTest is TestCommon {
// We need to set address(CCI) as the allowed caller and address(GARP) as the destination.
bytes memory approvedRemoteCaller = convertEVMTo65(address(CCI));
bytes memory remoteGARPImplementation = abi.encode(address(GARP));
// notice that remoteGARPImplementation needs to be encoded with how the AMB expectes it
// notice that remoteGARPImplementation needs to be encoded with how the AMB expects it
// and approvedRemoteCaller needs to be encoded with how GARP expects it.
CCI.connectNewChain(DESTINATION_IDENTIFIER, approvedRemoteCaller, remoteGARPImplementation);
}
Expand Down Expand Up @@ -505,4 +505,4 @@ Catalyst has been analyzed using Slither and no major bugs have been found. To r

`slither contracts/<>.sol --solc-args "--base-path . --include-path node_modules --optimize --optimize-runs 9000" --exclude naming-convention`

Alternativly, run `slither contracts` to analyze all contracts.
Alternatively, run `slither contracts` to analyze all contracts.
4 changes: 2 additions & 2 deletions evm/test/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ And then for larger tests of the system as a whole *./integration*
Tests may be sub-organised based on the function which they test. For example *./CatalystFactory/DeployVault.t.sol* tests the `deployVault` function in the Catalyst Factory.

*./TestCommon.t.sol*
Contains frequently used code snippits to simplify testing and inherits from other `Common` contracts which exposes other often uses macros.
Contains frequently used code snippits to simplify testing and inherits from other `Common` contracts which expose other often used macros.

*./mocks*
Contains various mocks used throughout testing.
Expand All @@ -43,4 +43,4 @@ For the simplest example, see *./CatalystVault/LocalSwap/LocalSwap.t.sol*. This

Many tests are implemented as invariant testing with fuzzing. An example of such a test is *./CatalystVault/LocalSwap/LocalSwap.t.sol*

The test *test_local_swap_invariance* is implemented as an fuzz test on the invariant. It collects vaults from the config and then tries various swap values and computes the invariant before and after the swap. If it decreased below a certain margin, then the test fails.
The test *test_local_swap_invariance* is implemented as a fuzz test on the invariant. It collects vaults from the config and then tries various swap values and computes the invariant before and after the swap. If it decreased below a certain margin, then the test fails.
4 changes: 2 additions & 2 deletions solana/programs/SwapPool/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ Users:
The steps to create and setup a new SwapPool are:
1. Create the pool with **create_swap_pool()**
- The transaction signer *setup_master* is set as the only authority allowed to make changes during the pool setup process.
- Internally, the Account that holds the SwapPool state is initialised, and rent is payed by the *setup_master*.
- Internally, the Account that holds the SwapPool state is initialised, and rent is paid by the *setup_master*.
- **TODO** Separate the payer from the *setup_master*?
2. Add assets (tokens) to the SwapPool via **add_swap_pool_asset()**
- The desired token mint account is added as an asset to the *SwapPoolState*.
Expand All @@ -35,7 +35,7 @@ The steps to create and setup a new SwapPool are:
1. The PDA is derived from the SwapPoolState public key, which can be kept private until the pool setup is complete.
2. **TODO CHECK** The entire setup process can be executed atomically.
- The authorities for the asset wallet and the token mint also have to be passed (PDAs too).
- Rent for the asset wallet and token mint is payed by the *setup_master*.
- Rent for the asset wallet and token mint is paid by the *setup_master*.
- **NOTE**: Assets are added individually, and not as group when calling *create_swap_pool()* (like with the EVM implementation), because Anchor does not (currently?) support passing arrays of accounts to instructions. Also, creation of the asset wallet and token mint is defined in the *add_swap_pool_asset* context definition (*AddSwapPoolAsset*); the way these are defined would make it incompatible with passing an array of asset accounts.
3. **TODO** Create SwapPool ICCS connection
4. Finish the setup via **finish_setup()**
Expand Down