diff --git a/README.md b/README.md index 537dbb5a..9c8218a6 100644 --- a/README.md +++ b/README.md @@ -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: @@ -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 diff --git a/evm/README.md b/evm/README.md index 878ee774..457d6058 100644 --- a/evm/README.md +++ b/evm/README.md @@ -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 @@ -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. @@ -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. @@ -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 @@ -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 @@ -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 @@ -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"; @@ -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); } @@ -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. diff --git a/evm/test/README.md b/evm/test/README.md index a5f5a931..81a037d4 100644 --- a/evm/test/README.md +++ b/evm/test/README.md @@ -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. @@ -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. \ No newline at end of file +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. diff --git a/solana/programs/SwapPool/README.md b/solana/programs/SwapPool/README.md index 55cb3044..82092f23 100644 --- a/solana/programs/SwapPool/README.md +++ b/solana/programs/SwapPool/README.md @@ -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*. @@ -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()**