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

update doc and readme #326

Merged
merged 3 commits into from
Aug 20, 2024
Merged
Show file tree
Hide file tree
Changes from 1 commit
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
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Tokenlon is a decentralized exchange and payment settlement protocol based on bl

## Architecture

Under construction
![Tokenlon Architecture](./Tokenlon-Architecture.png)

## Deployed contracts

Expand Down
Binary file added Tokenlon-Architecture.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
7 changes: 7 additions & 0 deletions doc/AllowanceTarget.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# AllowanceTarget

The AllowanceTarget contract manages token allowances and authorizes specific spenders to transfer tokens on behalf of users.

## Security Considerations

AllowanceTarget provides a pause mechanism to prevent unexpected situations. Only the contract owner can pause or unpause the contract. In most cases, the contract will not be paused.
2 changes: 1 addition & 1 deletion doc/CoordinatedTaker.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
# CoordinatedTaker

CoordinatedTaker is a conditional taker contract of LimitOrderSwap. It adds a fill permission design on the top of it. A permission of fill is issued by a coordinator with signature. If a user wants to fill an order, he needs to apply for the fill permission and submit the fill with it. The coordinator will manage the avaliable amount of each orders and only issue fill permission when the pending avaliable amount is enough. It helps avoiding fill collision and makes off-chain order canceling possible.
CoordinatedTaker is a conditional taker contract of LimitOrderSwap. It adds a fill permission design on the top of it. A permission of fill is issued by a coordinator with signature. If a user wants to fill an order, he needs to apply for the fill permission and submit the fill with it. The coordinator will manage the available amount of each orders and only issue fill permission when the pending available amount is enough. It helps avoiding fill collision and makes off-chain order canceling possible.
8 changes: 6 additions & 2 deletions doc/GenericSwap.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,11 @@
# GenericSwap

GenericSwap is a general token swapping contract that integrate with different strategy executors. The GS contract is responsible for ensuring the result of a swap is match the order. However, the actual swap is executed by a strategy executor. This design allows fulfilling an order with any combination of swapping protocols. Also, by adjusting payload in off-chain system, it may support new protocol without upgrading contracts.
GenericSwap is a general token swapping contract designed to integrate with various strategy executors (e.g. the `SmartOrderSwap` contract). The GenericSwap contract is responsible for ensuring a result of a swap is match the order. However, the actual swap is executed by a strategy executor. This design allows fulfilling an order with any combination of swapping protocols. Also, by adjusting payload in our off-chain system, it may support new protocol without upgrading contracts.

## Gas Saving Technical
alex0207s marked this conversation as resolved.
Show resolved Hide resolved

GenericSwap retains 1 wei of the maker token at the end of each swap transaction. This practice avoids repeatedly clearing the token balance to zero, as the EVM charges different gas fees for various storage states. By preventing frequent resets to zero, this approach effectively reduces gas consumption.

## Relayer

GS supports submitting a swap by a relayer with user signature. The hash of relayed swap should be recoreded to prevent replay attack.
The GenericSwap contract allows for trade submissions by a relayer with user's signatures. To prevent replay attacks, the hash of the relayed trade is recorded.
6 changes: 3 additions & 3 deletions doc/LimitOrderSwap.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,12 @@ A taker can optionally provide extra action parameter in payload which will be e

## FullOrKill

The default `fillLimitOrder` function allows the settled taking amount is less than a taker requested. The reason is that it may not be sufficient for the whole request when a trade is actual executed and the rest available taking amout would be the actual taking amount in that case. If a taker wants a non-adjustable taking amount, then the `fillLimitOrderFullOrKill` function should be called instead.
The default `fillLimitOrder` function allows the settled taking amount is less than a taker requested. The reason is that it may not be sufficient for the whole request when a trade is actual executed and the rest available taking amount would be the actual taking amount in that case. If a taker wants a non-adjustable taking amount, then the `fillLimitOrderFullOrKill` function should be called instead.

## GroupFill

If a group of orders can be fulfilled by each other, then no external liquiditiy is needed for settling those orders. A user can spot this kind of group with profits so it would be the incentive of searching and submitting it. In some cases, a user may need to add some external liquidity or create some orders so the group can be formed and settled.
If a group of orders can be fulfilled by each other, then no external liquidity is needed for settling those orders. A user can spot this kind of group with profits so it would be the incentive of searching and submitting it. In some cases, a user may need to add some external liquidity or create some orders so the group can be formed and settled.

## Fee

Some portion of maker asset of an order will be deducted as protocol fee. The fee will be transfered to `feeCollector` during the settlement. Each order may have different fee factor, it depends on the characteristic of an order.
Some portion of maker asset of an order will be deducted as protocol fee. The fee will be transferred to `feeCollector` during the settlement. Each order may have different fee factor, it depends on the characteristic of an order.
20 changes: 14 additions & 6 deletions doc/RFQ.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,26 @@
# RFQ

RFQ (Request For Quote) is a contract that settles a trade between two parties. Normally it requires an off-chain quoting system which provides quotes and signatures from certain makers. A user may request for a quote of a specific trading pair and size. Upon receiving the request, any maker willing to trade can respond with a quote to the user. If the user accepts it, then both parties will sign the trading order and submit the order with signatures to the RFQ contract. After verifying signatures, the RFQ contract will transfer tokens between user and maker accordingly.
The RFQ (Request For Quote) contract facilitates the settlement of trades between two parties: a market maker and an user. We provide an off-chain quoting system that handles the quoting process. Users can request quotes for specific trading pairs and sizes. Upon receiving a request, any interested maker can provide a quote to the user. If the user accepts the quote, both parties will sign the trading order and submit it ot the RFQ contract along with their signatures. The RFQ contract verifies the signatures and executes the token transfers between the user and the market maker.

## Order option flags

There are two options that the maker of a RFQ offer can set. The option flags is a uint256 field in the offer.
The maker of an RFQ offer can specify certain options using a `uint256` field in the offer, referred to as option flags:

- Partial fill : Whether the Offer can be filled partially or not (but once).
- Contract call : Whether the Offer can be filled by a contract or not.
- `FLG_ALLOW_CONTRACT_SENDER` : Determines whether the RFQ offer can be filled by a contract.
alex0207s marked this conversation as resolved.
Show resolved Hide resolved
- `FLG_ALLOW_PARTIAL_FILL` : Whether a RFQ offer can be filled partially or not (but once).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does (but once) mean here?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it indicates an RFQ order can be partial filled, but can only be filled once, regardless of any remaining quantity.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Revised version: Determines whether an RFQ offer can be partially filled. However, each RFQ order can only be filled once, regardless of whether it's fully or partially filled.

- `FLG_MAKER_RECEIVES_WETH` : Specifies whether a market maker is willing to receive WETH from a RFQ offer.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- `FLG_MAKER_RECEIVES_WETH` : Specifies whether a market maker is willing to receive WETH from a RFQ offer.
- `FLG_MAKER_RECEIVES_WETH` : Specifies whether a market maker wants the RFQ contract to wrap the ETH he received into WETH for him.


## Relayer

RFQ supports submitting a trade by a relayer with user signature. The hash of relayed trade should be recoreded to prevent replay attack.
The RFQ contract allows for trade submissions by a relayer with user's signatures. To prevent replay attacks, the hash of the relayed trade is recorded.

## Fee

Some portion of maker asset of an order will be deducted as protocol fee. The fee will be transfered to `feeCollector` during the settlement. Each order may have different fee factor, it depends on the characteristic of an order.
A portion of the maker's asset in the order will be deducted as a protocol fee. This fee is transferred to the feeCollector during settlement.
alex0207s marked this conversation as resolved.
Show resolved Hide resolved

The fee factor is composed of two parts:

1. Protocol Fee
2. Gas Fee

If a relayer submits the trade on-chain, the gas fee will be adjusted according to the on-chain conditions at the time of the transaction.
alex0207s marked this conversation as resolved.
Show resolved Hide resolved
6 changes: 5 additions & 1 deletion doc/SmartOrderStrategy.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
# SmartOrderStrategy

SmartOrderStrategy is a strategy executor of a generic swap. It should be called by GenericSwap contract and preform any swaps according to provided payload. This contract should not has any balance or token approval since it could perform any arbitary calls. Also the `executeStrategy` function is only allowed to be called by GenericSwap contract.
SmartOrderStrategy is a strategy executor of a generic swap. It is designed to be called by the `GenericSwap contract` and performs swaps according to the provided payload. This contract should not hold any significant token balance or require token approvals, as it can execute arbitrary calls. Additionally, the `executeStrategy` function is restricted to being called only by the GenericSwap contract.
alex0207s marked this conversation as resolved.
Show resolved Hide resolved

## Gas Saving Technical

SmartOrderStrategy retains 1 wei of the maker token at the end of each swap transaction. This practice avoids repeatedly clearing the token balance to zero, as the EVM charges different gas fees for various storage states. By preventing frequent resets to zero, this approach effectively reduces gas consumption.
alex0207s marked this conversation as resolved.
Show resolved Hide resolved
4 changes: 3 additions & 1 deletion doc/TokenCollector.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
# TokenCollector

In Tokenlon V6, multiple schemes of token approval is supported. TokenCollector is an abstract contract that handles different ways of token transfering. When interacting with Tokenlon, user can choose one of supported approving scheme and prepare the corresponded Tokenlon permit parameter (in bytes). The first byte of the permit indicate the type and the rest are encoded data with type specific structure.
`TokenCollector` is an abstract contract designed to handle various token collection mechanisms. It supports different methods of token transfer, allowing flexibility in interacting with Tokenlon and other token standards.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

... allowing flexibility in interacting with Tokenlon and other token standards

What does this mean?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This means:

  • Tokenlon uses TokenCollector to collect user's tokens.

  • It supports multiple schemes to interact with various token types.

This flexibility allows TokenCollector to handle different token standards and transfer methods efficiently.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The flexibility is used to describe "TokenCollector" however "users" are the ones "interacting with" Tokenlon so it's better to differentiate them in your sentence. For example:

Suggested change
`TokenCollector` is an abstract contract designed to handle various token collection mechanisms. It supports different methods of token transfer, allowing flexibility in interacting with Tokenlon and other token standards.
`TokenCollector` is an abstract contract designed to handle various token collection mechanisms. It supports different methods of token transfer, giving users flexibility when interacting with Tokenlon and other token standards.

Or

Suggested change
`TokenCollector` is an abstract contract designed to handle various token collection mechanisms. It supports different methods of token transfer, allowing flexibility in interacting with Tokenlon and other token standards.
`TokenCollector` is an abstract contract designed to handle various token collection mechanisms. It supports different methods of token transfer across different token standards. Users have great flexibility in token authorization when interacting with Tokenlon.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also it seems TokenCollector should be a base contract instead of an abstract contract as it does not have any virtual functions.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It simply describes that we actually define TokenCollector as an abstract contract.


When interacting with Tokenlon, users can select one of the supported approval schemes and provide the corresponding parameters in the data field (encoded in bytes). The first byte of this data indicates the type of the scheme, followed by the encoded data specific to that type.
alex0207s marked this conversation as resolved.
Show resolved Hide resolved

```
// ***********************************
Expand Down
Loading