Liquidity.Party/tycho-protocol-sdk
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Small improvements to the docs

Browse Source
This commit is contained in:
Michał D
2023-12-08 16:59:09 +01:00
parent a7798374e1
commit 194e7caa15
5 changed files with 63 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/README.md
View File

@@ -2,25 +2,25 @@
Protocol lib is a library used by Propellerheads.xyz solvers to integrate decentralized protocols. Currently, only swap/exchange protocols are supported.
### Integration Process
## Integration Process
To integrate with PropellerHeads solvers, two components need to be provided:
* **Protocol logic:** Provides simulations, of the protocols logic.
* **Protocol logic:** Provides simulations of the protocols logic.
* **Indexing**: Provides access to the protocol state used by the simulation. This component is optional if your protocol is stateless.
#### Protocol Logic
### Protocol Logic
PropellerHeads currently exposes two integration modes to specify the protocols' underlying logic:
* **VM Integration:** This integration type requires implementing an adapter interface in any language that compiles to the respective vm byte code. Currently, only Solidity is supported.
* **VM Integration:** This integration type requires implementing an adapter interface in any language that compiles to the respective vm byte code. This SDK provides the interface only in Solidity. **[Read more here.](logic/vm-integration/README.md)**
* **Native Rust Integration:** Coming soon, this integration type requires implementing a Rust trait that describes the protocol logic.
While VM integration is certainly the quickest and probably most accessible one for protocol developers, native implementations are much faster and allow us to consider the protocol for more time-sensitive use cases - e.g. quoting.
#### Indexing
### Indexing
For indexing purposes, it is required that you provide a [substreams](https://thegraph.com/docs/en/substreams/) package that emits a specified set of messages. Most new protocols will already have a [substreams](https://thegraph.com/docs/en/substreams/) package for indexing implemented this will only need to be adjusted to emit the required messages.
For indexing purposes, it is required that you provide a [substreams](https://thegraph.com/docs/en/substreams/) package that emits a specified set of messages. If your protocol already has a [substreams](https://thegraph.com/docs/en/substreams/) package for indexing implemented, you can adjust it to emit the required messages.
_Specifications coming soon._

46
docs/logic/vm-integration/README.md
View File

@@ -2,41 +2,53 @@
This page describes the interface required to implement protocol logic component.
To create a VM implementation, it is required two provide a manifest file as well as a implementation of the corresponding adapter interface.
To create a VM integration, it is required to provide a manifest file as well as an implementation of the corresponding adapter interface.
## Examples
Following exchanges have been integrated using VM approach:
- Uniswap V2 (see `/evm/src/uniswap-v2`)
- Balancer V2 (see `/evm/src/balancer-v2`)
## Step by step
### Prerequisites
1. Install [Foundry](https://book.getfoundry.sh/getting-started/installation#using-foundryup).
```bash
curl -L https://foundry.paradigm.xyz | bash
```
```bash
curl -L https://foundry.paradigm.xyz | bash
```
then start a new terminal session and run
```bash
foundryup
```
2. Start by making a local copy of the Propeller Protocol Lib repository:
```bash
git clone https://github.com/propeller-heads/propeller-protocol-lib
```
```bash
git clone https://github.com/propeller-heads/propeller-protocol-lib
```
3. Install forge dependencies:
```bash
cd ./propeller-protocol-lib/evm/
forge install
```
```bash
cd ./propeller-protocol-lib/evm/
forge install
```
### Understanding the ISwapAdapter
1. Read the the documentation of the [Ethereum Solidity interface](ethereum-solidity.md). It describes the functions that need to be implemented as well as the manifest file.
2. Additionally read through the docstring of the [ISwapAdapter.sol](../../../evm/src/interfaces/ISwapAdapter.sol) interface and the [ISwapAdapterTypes.sol](../../../evm/src/interfaces/ISwapAdapterTypes.sol) interface which defines the data types and errors used by the adapter interface.
3. You can also generate the documentation locally and the look at the generated documentation in the `./docs` folder:
```bash
forge doc
```
```bash
cd ./propeller-protocol-lib/evm/
forge doc
```
### Implementing the ISwapAdapter interface
1. Your integration should be in a separate directory in the `evm/src` folder. Start by cloning the template directory:
```bash
cp -r ./evm/src/template ./evm/src/<your-adapter-name>
```
```bash
cp -r ./evm/src/template ./evm/src/<your-adapter-name>
```
2. Implement the `ISwapAdapter` interface in the `./evm/src/<your-adapter-name>.sol` file.
3. Create tests for your implementation in the `./evm/test/<your-adapter-name>.t.sol` file, again based on the template `./evm/test/TemplateSwapAdapter.t.sol`.

30
docs/logic/vm-integration/ethereum-solidity.md
View File

@@ -4,12 +4,12 @@ description: Provide protocol logic using the ethereum virtual machine
# Ethereum: Solidity
### Swap
## Swap/exchange protocol
To integrate an EVM exchange protocol the [ISwapAdapter.sol ](https://github.com/propeller-heads/propeller-protocol-lib/blob/main/evm/interfaces/ISwapAdapter.sol)should be implemented. Additionally a manifest file is required that summarises some metadata about the protocol.
{% hint style="info" %}
Although the interface is specified for Solidity, you are not limited to writing the adapater contract in solidity. We can use any compiled evm bytecode. So if you prefer e.g. Vyper you are welcome to implement the interface using vyper. Unfortunately we do not provide all the tooling for vyper contracts yet, but you can certainly submit compiled vyper byte code.
Although the interface is specified for Solidity, you are not limited to writing the adapater contract in Solidity. We can use any compiled evm bytecode. So if you prefer e.g. Vyper, you are welcome to implement the interface using Vyper. Unfortunately we do not provide all the tooling for Vyper contracts yet, but you can certainly submit compiled Vyper byte code.
{% endhint %}
The manifest file contains information about the author, as well as additional static information about the protocol and how to test the current implementation. The file below lists all valid keys.
@@ -22,9 +22,10 @@ author:
# Protocol Constants
constants:
# The minimum gas usage of the protocol, excluding any token transfers
# The minimum gas usage of a swap using the protocol, excluding any token transfers
protocol_gas: 30000
# Minimum capabilities we can expect, individual pools may extend these
# Minimum capabilities we can expect, individual pools may extend these.
# To learn about Capabilities, see ISwapAdapter.sol
capabilities:
- SellSide
- BuySide
@@ -32,17 +33,18 @@ constants:
# The files containing the adapter contract (byte)code
contract:
# The contract bytecode (required if no source is provided)
# The contract runtime (i.e. deployed) bytecode (required if no source is provided)
runtime: UniswapV2SwapAdapter.bin
# If you submit the source our CI can generate the bytecode
source: UniswapV2SwapAdapter.sol
# Deployment instances used to generate chain specific bytecode.
# Deployment instances used to generate chain-specific bytecode.
# Used by the runtime bytecode build script.
instances:
- chain:
name: mainnet
id: 0
# Arguments passed to the constructor when building the contract
arguments:
- "0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f"
@@ -63,9 +65,11 @@ tests:
Calculates pool prices for specified amounts (optional).
The returned prices should include all protocol fees, in case the fee is dynamic, the returned price is expected to include the minimum fee.&#x20;
The returned prices should be in `buyToken/sellToken` units.
Ideally this method should be implemented, although it is optional as the price function can be numerically estimated from the swap function. In case it is not available it should be flagged accordingly via capabilities and calling it should revert using the NotImplemented error.&#x20;
The returned prices should include all protocol fees. In case the fee is dynamic, the returned price is expected to include the minimum fee.
Ideally this method should be implemented, although it is optional as the price function can be numerically estimated from the swap function. In case it is not available, it should be flagged accordingly via capabilities, and calling it should revert using the NotImplemented error.
The method needs to be implemented as view as this is usually more efficient and can be run in parallel.
@@ -82,11 +86,11 @@ function price(
Simulates swapping tokens on a given pool.
This function should be state modifying meaning it should actually execute the swap and change the state of the vm accordingly.
This function should be state modifying, meaning it should actually execute the swap and change the state of the VM accordingly.
Please include a gas usage estimate for each amount. This can be achieved e.g. by using the gasleft() function.
Please include a gas usage estimate for each amount. This can be achieved e.g. by using the `gasleft()` function.
The return type Trade, has a price attribute which should contain the value of price(specifiedAmount). As previously mentioned, the price function support is optional, it is valid to return a zero value for this price in that case it will be estimated numerically. To return zero please use Fraction(0, 1).
The return type `Trade` has a price attribute which should contain the value of `price(specifiedAmount)`. As previously mentioned, the price function support is optional, it is valid to return a zero value for this price (in that case it will be estimated numerically). To return zero please use `Fraction(0, 1)`.
```solidity
function swap(
@@ -102,7 +106,7 @@ function swap(
Retrieves the limits for each token.
This method returns the maximum limits of a token that can be traded. The limit is reached when the change in the received amounts is zero or close to zero. If in doubt over estimate the limit. The swap function should not error with LimitExceeded if called with any amounts below the limit.
This method returns the maximum amount of a token that can be traded. The limit is reached when the change in the received amounts is zero or close to zero. If in doubt, overestimate the limit. The swap function should not error with LimitExceeded if called with any amounts below the limit.
```solidity
function getLimits(bytes32 poolId, OrderSide side)
@@ -136,7 +140,7 @@ function getTokens(bytes32 poolId)
Retrieves a range of pool IDs.
_Mainly used for testing it is alright to not return all available pools here. Nevertheless this is useful to test against the substreams implementation. If implemented it safes time writing custom tests._
_Mainly used for testing. It is alright to not return all available pools here. Nevertheless, this is useful to test against the substreams implementation. If implemented, it saves time writing custom tests._
```solidity
function getPoolIds(uint256 offset, uint256 limit)