{"id":22072607,"url":"https://github.com/broxus/dex-middleware","last_synced_at":"2025-03-23T19:24:31.229Z","repository":{"id":193516097,"uuid":"688886438","full_name":"broxus/dex-middleware","owner":"broxus","description":null,"archived":false,"fork":false,"pushed_at":"2023-09-25T10:47:29.000Z","size":4111,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-01-29T02:47:06.395Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/broxus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-09-08T10:05:54.000Z","updated_at":"2023-10-05T17:22:25.000Z","dependencies_parsed_at":"2023-09-08T14:45:38.828Z","dependency_job_id":"d6661b96-58b0-46bb-a031-8829c431ced5","html_url":"https://github.com/broxus/dex-middleware","commit_stats":null,"previous_names":["broxus/dex-middleware"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/broxus%2Fdex-middleware","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/broxus%2Fdex-middleware/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/broxus%2Fdex-middleware/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/broxus%2Fdex-middleware/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/broxus","download_url":"https://codeload.github.com/broxus/dex-middleware/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245155525,"owners_count":20569715,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-30T21:13:55.463Z","updated_at":"2025-03-23T19:24:31.199Z","avatar_url":"https://github.com/broxus.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DEX middleware - DeFi utility for making multi swaps, multi sends, multi burn, and combining it\r\n\r\n## Deploy\r\nUpdate `.env` file\r\n```shell\r\nnpm i\r\n```\r\n```shell\r\nnpm run deploy-main\r\n```\r\n\r\n\r\n\r\n## Entry point overview\r\n1. First of all need to create a transfer payload via `DexMiddleware.buildPayload`. Each of the prams (except remainingTokensTo) can be an empty array\r\n```solidity\r\n function buildPayload(\r\n     CommonStructures.PayloadForDex[] _payloadsForDex, // multi-swap config\r\n     CommonStructures.PayloadForTransfer[] _payloadsForTransfers, // tokens multi-send config\r\n     CommonStructures.PayloadForBurn[] _payloadsForBurn, // tokens multi-burn config\r\n     CommonStructures.PayloadForUnwrap[] _payloadForUnwrap,\r\n     address remainingTokensTo // remaining tokens receiver\r\n ) override external pure returns (TvmCell);\r\n```\r\n2. Then calculate the required tokens and evers amount via `DexMiddleware.buildPayload` (optional step, but it can save mistakes)\r\n```solidity\r\n function calculateFeeAndTokensValue(\r\n      CommonStructures.PayloadForDex[] _payloadsForDex,\r\n      CommonStructures.PayloadForTransfer[] _payloadsForTransfer,\r\n      CommonStructures.PayloadForBurn[] _payloadsForBurn,\r\n      CommonStructures.PayloadForUnwrap[] _payloadForUnwrap\r\n ) override public pure returns (CommonStructures.CalculationResult);\r\n```\r\n3. Send payload from step 1 with tokens and evers amount from point 2\r\n\r\n\r\n## Multi-swap overview\r\nA user can make an endless count of swaps in a single transaction with configuration success and cancel destination behavior.\r\n\r\nLet's look at `CommonStructures.PayloadForDex` struct\r\n```solidity\r\nstruct PayloadForDex {\r\n     TvmCell dexPayload; //tokens transfer payload calculated by dex\r\n     uint32 leaves; // count of successful transactions that dex will send\r\n     address firstRoot; // entry pool address\r\n     address remainingGasTo;\r\n     uint128 tokensAmount; // amount of tokens that will be attached to the first transfer (first root) \r\n     uint128 valueForDexOperation; // ever value that will be attached to the first transfer\r\n     uint128 deployWalletValue;\r\n     mapping (address =\u003e address[]) rootToSendersAllowanceMap; // *rootToSendersAllowanceMap\r\n     FinishTransaction successPayload; // * FinishTransaction\r\n     FinishTransaction cancelPayload;// * FinishTransaction\r\n }\r\n```\r\n`rootToSendersAllowanceMap` - security field that prevents not expected transfers to the swap flow.\r\n\r\nIt should be configured with next rules:\r\n- keys of this mapping is the allowed token root\r\n\r\n- values of this mapping is the allowed senders array of this token\r\n\r\n`FinishTransaction successPayload` and `FinishTransaction cancelPayload` destination behavior\r\n```solidity\r\n struct FinishTransaction {\r\n     address tokenReceiver;\r\n     uint128 valueForFinalTransfer; // how many evers should be attached to the destination transfer\r\n     uint128 deployWalletValue;\r\n     TvmCell payload; // payload for destination transfer\r\n }\r\n```\r\n### Different between `successPayload` and `cancelPayload`\r\nDex swap includes so-called splits which mean transactions can be split to some other transaction.\r\nEach split transaction can be `cancel` or `success`, so one of the main task of this project is\r\ndeciding of type of transaction and making the final transfer to the `success` or `cancel` destination point\r\n\r\n## Multi-send overview\r\nA user can make an endless count of transactions in a single transaction\r\n\r\nLet's look at `CommonStructures.PayloadForTransfer`\r\n```solidity\r\n struct PayloadForTransfer {\r\n    address receiver; // tokens receiver\r\n    address _remainingGasTo;\r\n    uint128 amount; // tokens amount\r\n    TvmCell payload; // payload for transfer\r\n    uint128 attachedValue; // ever value for transfer\r\n    uint128 deployWalletValue;\r\n    bool notify;\r\n}\r\n```\r\nThis payload extended from `ITokenWallet.transfer` method but with some additional fields\r\n\r\n## Multi-burn overview\r\nA user can make an endless count of burns\r\nLet's look at `CommonStructures.PayloadForBurn`\r\n```solidity\r\n struct PayloadForBurn {\r\n     address callbackTo; // who will be notified about tokens burn\r\n     address remainingGasTo;\r\n     uint128 amount; // burn amount\r\n     TvmCell payload; // payload for burn receiver\r\n     uint128 attachedValue; // ever value for burn receiver\r\n }\r\n```\r\nThis payload extended from `IBurnableTokenWallet.burn` method but with some additional fields\r\n\r\n# Hints\r\nWith Dex-Middleware we can build so huge flow in a single transaction.\r\nExample flow:\r\n1. Swap 100 USDT -\u003e 0.1 WBTC\r\n2. Send to three users  0.01 WBTC each\r\n3. Burn 0.06 WBTC for the bridge contract\r\n   And after this flow `remainingTokensTo` receiver will receive an extra amount of WBTC\r\n\r\n# Api usage\r\nexamples of API usage can be found inside `scripts/e2e` \r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbroxus%2Fdex-middleware","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbroxus%2Fdex-middleware","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbroxus%2Fdex-middleware/lists"}