grassrootseconomics/sarafu-vise

Fork 0

Pool Swap Menu Flow #24

New Issue

Open

opened 2025-02-19 14:07:25 +01:00 by carlos · 2 comments

carlos commented

2025-02-19 14:07:25 +01:00

Member

We came up with a simple sketch on how the menu will look like with the introduction of the pool swap .We anticipate that the flow will be as here:

https://app.eraser.io/workspace/E8YvxTTqLze700xUSez3

Suggestions and any improvements before implementation will be appreciated.

We came up with a simple sketch on how the menu will look like with the introduction of the pool swap .We anticipate that the flow will be as here: https://app.eraser.io/workspace/E8YvxTTqLze700xUSez3 Suggestions and any improvements before implementation will be appreciated.

carlos added the

Kind/Feature

label 2025-02-20 07:02:54 +01:00

carlos added the

Priority

Low

label 2025-02-20 07:05:20 +01:00

carlos added

and removed

labels 2025-02-20 07:21:46 +01:00

kamikazechaser commented

2025-02-21 07:40:23 +01:00

Owner

User should be able to select a pool from a list or enter the pool symbol manually. The list will be provided by an API. An additional endpoint will be provided to fetch a pool's details given its symbol.

API endpoint to fetch pool list
API endpoint to resolve pool details from pool symbol

2. Select voucher symbol to swap FROM

User should be able to choose the voucher symbol to swap from from a list. The list will be provided by an API. Generally they won't need to enter the voucher symbol because we will check it against their current holdings and populate the list accordingly.

API endpoint to fetch voucher list that the user can swap FROM

3. Select voucher symbol to swap TO

User should be able to choose the voucher symbol to swap from from a list. The list will be provided by an API endpoint. Priority is given to popular stable coins available.

API endpoint to fetch voucher list that the user can swap TO

4. Display voucher swap limits Display the max FROM token

~~Ensure that the limits have the symbol suffixed. e.g. Max 10 SRF, Min 1 SRF. The limits will be provided by an API endpoint.~~

API endpoint to display possible limits of swap

4. Swap preview

Display the swap preview and estimates. This will be provided by an API endpoint.

API endpoint to display swap preview.

5. Execute swap

Send a request to the custodial system.

## 1. Select pool menu User should be able to select a pool from a list or enter the pool symbol manually. The list will be provided by an API. An additional endpoint will be provided to fetch a pool's details given its symbol. - [x] API endpoint to fetch pool list - [x] API endpoint to resolve pool details from pool symbol ## 2. Select voucher symbol to swap FROM User should be able to choose the voucher symbol to swap from from a list. The list will be provided by an API. Generally they won't need to enter the voucher symbol because we will check it against their current holdings and populate the list accordingly. - [x] API endpoint to fetch voucher list that the user can swap FROM ## 3. Select voucher symbol to swap TO User should be able to choose the voucher symbol to swap from from a list. The list will be provided by an API endpoint. Priority is given to popular stable coins available. - [x] API endpoint to fetch voucher list that the user can swap TO ## 4. ~~Display voucher swap limits~~ Display the max FROM token ~~Ensure that the limits have the symbol suffixed. e.g. Max 10 SRF, Min 1 SRF. The limits will be provided by an API endpoint.~~ - [x] API endpoint to display possible limits of swap ## 4. Swap preview Display the swap preview and estimates. This will be provided by an API endpoint. - [x] API endpoint to display swap preview. ## 5. Execute swap Send a request to the custodial system.

kamikazechaser commented

2025-02-25 11:50:37 +01:00

Owner

Example:

1

This endpoint lists the top pools to display as a list

> GET http://localhost:5006/api/v1/pool/top
> authorization: Bearer eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJwdWJsaWNLZXkiOiIweDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAiLCJzZXJ2aWNlIjp0cnVlLCJpc3MiOiJldGgtY3VzdG9kaWFsLWRldiIsInN1YiI6InNuLXByb2QiLCJleHAiOjE3Njk4NDIxNzksImlhdCI6MTczODMwNjE3OX0.FXTwZ8nQKCG66xO0wMbx4Mga8SqFZcm65pq7_iMKjXPMH_h0IBHmSV2DOKQVfNbI1W9BRUCuSUwbALFgDqLrBg

{
  "ok": true,
  "description": "Top 5 pools sorted by swaps",
  "result": {
    "topPools": [
      {
        "poolName": "Kenya ROLA Pool",
        "poolSymbol": "ROLA",
        "poolContractAddress": "0x48a953cA5cf5298bc6f6Af3C608351f537AAcb9e",
        "limiterAddress": "",
        "voucherRegistry": ""
      },
      {
        "poolName": "Nairobi ROLA Pool",
        "poolSymbol": "NAIROBI",
        "poolContractAddress": "0xB0660Ac1Ee3d32ea35bc728D7CA1705Fa5A37528",
        "limiterAddress": "",
        "voucherRegistry": ""
      },
      {
        "poolName": "Friends of Kiriba Ecosystem ",
        "poolSymbol": "FRIENDS",
        "poolContractAddress": "0xC4848263821FA02baB2181910A2eFb9CECb2c21C",
        "limiterAddress": "",
        "voucherRegistry": ""
      },
      {
        "poolName": "Resilient Community Waqfs",
        "poolSymbol": "REZILIENS",
        "poolContractAddress": "0x1e40951d7a28147D8B4A554C60c42766C92e2Fc6",
        "limiterAddress": "",
        "voucherRegistry": ""
      },
      {
        "poolName": "GrE Tech",
        "poolSymbol": "GRET",
        "poolContractAddress": "0xb7B9d0A264eD1a8E2418571B7AC5933C79C9c2B8",
        "limiterAddress": "",
        "voucherRegistry": ""
      }
    ]
  }
}

If a user inputs a custom pool symbol:

> GET http://localhost:5006/api/v1/pool/reverse/DEVT
> authorization: Bearer eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJwdWJsaWNLZXkiOiIweDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAiLCJzZXJ2aWNlIjp0cnVlLCJpc3MiOiJldGgtY3VzdG9kaWFsLWRldiIsInN1YiI6InNuLXByb2QiLCJleHAiOjE3Njk4NDIxNzksImlhdCI6MTczODMwNjE3OX0.FXTwZ8nQKCG66xO0wMbx4Mga8SqFZcm65pq7_iMKjXPMH_h0IBHmSV2DOKQVfNbI1W9BRUCuSUwbALFgDqLrBg

{
  "ok": true,
  "description": "Pool details",
  "result": {
    "poolDetails": {
      "poolName": "DevTest",
      "poolSymbol": "DEVT",
      "poolContractAddress": "0x145F87d6198dEDD45C614FFD8b70E9a2fCCc5cc9",
      "limiterAddress": "",
      "voucherRegistry": ""
    }
  }
}

2

This endpoint automatically finds out all the possible tokens a user can select to swap from. Note that this endpoint can take up to 3 seconds to completely resolve due to the nature of checking against the voucher registry and comparing user holdings since these values need to be checked on chain.

# /pool/:pool/from/:address
> GET http://localhost:5006/api/v1/pool/0x48a953cA5cf5298bc6f6Af3C608351f537AAcb9e/from/0x5523058cdFfe5F3c1EaDADD5015E55C6E00fb439
> authorization: Bearer eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJwdWJsaWNLZXkiOiIweDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAiLCJzZXJ2aWNlIjp0cnVlLCJpc3MiOiJldGgtY3VzdG9kaWFsLWRldiIsInN1YiI6InNuLXByb2QiLCJleHAiOjE3Njk4NDIxNzksImlhdCI6MTczODMwNjE3OX0.FXTwZ8nQKCG66xO0wMbx4Mga8SqFZcm65pq7_iMKjXPMH_h0IBHmSV2DOKQVfNbI1W9BRUCuSUwbALFgDqLrBg

{
  "ok": true,
  "description": "Swap from list",
  "result": {
    "filtered": [
      {
        "contractAddress": "0xc7B78Ac9ACB9E025C8234621FC515bC58179dEAe",
        "tokenSymbol": "AMANI",
        "tokenDecimals": "6",
        "balance": ""
      },
      {
        "contractAddress": "0xF0C3C7581b8b96B59a97daEc8Bd48247cE078674",
        "tokenSymbol": "AMUA",
        "tokenDecimals": "6",
        "balance": ""
      },
      {
        "contractAddress": "0x371455a30fc62736145Bd8429Fcc6481186f235F",
        "tokenSymbol": "BAHARI",
        "tokenDecimals": "6",
        "balance": ""
      },
      {
        "contractAddress": "0x7cA6113b59c24a880F382C7E12d609a6Eb05246b",
        "tokenSymbol": "BANGLA",
        "tokenDecimals": "6",
        "balance": ""
      }
      // trimmed
    ]
  }
}

3

This endpoint returns the list of possible vouchers to swap to. Since this list could almost always contain all possible vouchers in the pool, it temporarily only displays stable coins available in the pool since that is the most common out token.

# /pool/:pool/to/:address
> GET http://localhost:5006/api/v1/pool/0x48a953cA5cf5298bc6f6Af3C608351f537AAcb9e/to/0x5523058cdFfe5F3c1EaDADD5015E55C6E00fb439
> authorization: Bearer eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJwdWJsaWNLZXkiOiIweDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAiLCJzZXJ2aWNlIjp0cnVlLCJpc3MiOiJldGgtY3VzdG9kaWFsLWRldiIsInN1YiI6InNuLXByb2QiLCJleHAiOjE3Njk4NDIxNzksImlhdCI6MTczODMwNjE3OX0.FXTwZ8nQKCG66xO0wMbx4Mga8SqFZcm65pq7_iMKjXPMH_h0IBHmSV2DOKQVfNbI1W9BRUCuSUwbALFgDqLrBg

{
  "ok": true,
  "description": "Swap to list",
  "result": {
    "filtered": [
      {
        "contractAddress": "0x765DE816845861e75A25fCA122bb6898B8B1282a",
        "tokenSymbol": "cUSD",
        "tokenDecimals": "18",
        "balance": ""
      }
    ]
  }
}

4

This endpoint returns the max FROM token only. This is sufficient to determine whether to proceed to the next step or not and follows a similar UX to sarafu.network. It is important to check if max/tokenDecimals > 0.1 for UX purposes and to prevent swapping of dust values.

# /pool/:pool/limit/:from/:to/:address
> GET http://localhost:5006/api/v1/pool/0x48a953cA5cf5298bc6f6Af3C608351f537AAcb9e/limit/0x078b3a26596218507781722A4e8825BFB9570Fba/0x765DE816845861e75A25fCA122bb6898B8B1282a/0x5523058cdFfe5F3c1EaDADD5015E55C6E00fb439
> authorization: Bearer eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJwdWJsaWNLZXkiOiIweDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAiLCJzZXJ2aWNlIjp0cnVlLCJpc3MiOiJldGgtY3VzdG9kaWFsLWRldiIsInN1YiI6InNuLXByb2QiLCJleHAiOjE3Njk4NDIxNzksImlhdCI6MTczODMwNjE3OX0.FXTwZ8nQKCG66xO0wMbx4Mga8SqFZcm65pq7_iMKjXPMH_h0IBHmSV2DOKQVfNbI1W9BRUCuSUwbALFgDqLrBg

{
  "ok": true,
  "description": "From token max limit",
  "result": {
    "max": "1339482"
  }
}

5

Refer to eth-custodial docs.

Example: # 1 This endpoint lists the top pools to display as a list ```bash > GET http://localhost:5006/api/v1/pool/top > authorization: Bearer eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJwdWJsaWNLZXkiOiIweDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAiLCJzZXJ2aWNlIjp0cnVlLCJpc3MiOiJldGgtY3VzdG9kaWFsLWRldiIsInN1YiI6InNuLXByb2QiLCJleHAiOjE3Njk4NDIxNzksImlhdCI6MTczODMwNjE3OX0.FXTwZ8nQKCG66xO0wMbx4Mga8SqFZcm65pq7_iMKjXPMH_h0IBHmSV2DOKQVfNbI1W9BRUCuSUwbALFgDqLrBg ``` ```json { "ok": true, "description": "Top 5 pools sorted by swaps", "result": { "topPools": [ { "poolName": "Kenya ROLA Pool", "poolSymbol": "ROLA", "poolContractAddress": "0x48a953cA5cf5298bc6f6Af3C608351f537AAcb9e", "limiterAddress": "", "voucherRegistry": "" }, { "poolName": "Nairobi ROLA Pool", "poolSymbol": "NAIROBI", "poolContractAddress": "0xB0660Ac1Ee3d32ea35bc728D7CA1705Fa5A37528", "limiterAddress": "", "voucherRegistry": "" }, { "poolName": "Friends of Kiriba Ecosystem ", "poolSymbol": "FRIENDS", "poolContractAddress": "0xC4848263821FA02baB2181910A2eFb9CECb2c21C", "limiterAddress": "", "voucherRegistry": "" }, { "poolName": "Resilient Community Waqfs", "poolSymbol": "REZILIENS", "poolContractAddress": "0x1e40951d7a28147D8B4A554C60c42766C92e2Fc6", "limiterAddress": "", "voucherRegistry": "" }, { "poolName": "GrE Tech", "poolSymbol": "GRET", "poolContractAddress": "0xb7B9d0A264eD1a8E2418571B7AC5933C79C9c2B8", "limiterAddress": "", "voucherRegistry": "" } ] } } ``` If a user inputs a custom pool symbol: ```bash > GET http://localhost:5006/api/v1/pool/reverse/DEVT > authorization: Bearer eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJwdWJsaWNLZXkiOiIweDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAiLCJzZXJ2aWNlIjp0cnVlLCJpc3MiOiJldGgtY3VzdG9kaWFsLWRldiIsInN1YiI6InNuLXByb2QiLCJleHAiOjE3Njk4NDIxNzksImlhdCI6MTczODMwNjE3OX0.FXTwZ8nQKCG66xO0wMbx4Mga8SqFZcm65pq7_iMKjXPMH_h0IBHmSV2DOKQVfNbI1W9BRUCuSUwbALFgDqLrBg ``` ```json { "ok": true, "description": "Pool details", "result": { "poolDetails": { "poolName": "DevTest", "poolSymbol": "DEVT", "poolContractAddress": "0x145F87d6198dEDD45C614FFD8b70E9a2fCCc5cc9", "limiterAddress": "", "voucherRegistry": "" } } } ``` # 2 This endpoint automatically finds out all the possible tokens a user can select to swap from. Note that this endpoint can take up to 3 seconds to completely resolve due to the nature of checking against the voucher registry and comparing user holdings since these values need to be checked on chain. ```bash # /pool/:pool/from/:address > GET http://localhost:5006/api/v1/pool/0x48a953cA5cf5298bc6f6Af3C608351f537AAcb9e/from/0x5523058cdFfe5F3c1EaDADD5015E55C6E00fb439 > authorization: Bearer eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJwdWJsaWNLZXkiOiIweDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAiLCJzZXJ2aWNlIjp0cnVlLCJpc3MiOiJldGgtY3VzdG9kaWFsLWRldiIsInN1YiI6InNuLXByb2QiLCJleHAiOjE3Njk4NDIxNzksImlhdCI6MTczODMwNjE3OX0.FXTwZ8nQKCG66xO0wMbx4Mga8SqFZcm65pq7_iMKjXPMH_h0IBHmSV2DOKQVfNbI1W9BRUCuSUwbALFgDqLrBg ``` ```json { "ok": true, "description": "Swap from list", "result": { "filtered": [ { "contractAddress": "0xc7B78Ac9ACB9E025C8234621FC515bC58179dEAe", "tokenSymbol": "AMANI", "tokenDecimals": "6", "balance": "" }, { "contractAddress": "0xF0C3C7581b8b96B59a97daEc8Bd48247cE078674", "tokenSymbol": "AMUA", "tokenDecimals": "6", "balance": "" }, { "contractAddress": "0x371455a30fc62736145Bd8429Fcc6481186f235F", "tokenSymbol": "BAHARI", "tokenDecimals": "6", "balance": "" }, { "contractAddress": "0x7cA6113b59c24a880F382C7E12d609a6Eb05246b", "tokenSymbol": "BANGLA", "tokenDecimals": "6", "balance": "" } // trimmed ] } } ``` # 3 This endpoint returns the list of possible vouchers to swap to. Since this list could almost always contain all possible vouchers in the pool, it temporarily only displays stable coins available in the pool since that is the most common out token. ```bash # /pool/:pool/to/:address > GET http://localhost:5006/api/v1/pool/0x48a953cA5cf5298bc6f6Af3C608351f537AAcb9e/to/0x5523058cdFfe5F3c1EaDADD5015E55C6E00fb439 > authorization: Bearer eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJwdWJsaWNLZXkiOiIweDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAiLCJzZXJ2aWNlIjp0cnVlLCJpc3MiOiJldGgtY3VzdG9kaWFsLWRldiIsInN1YiI6InNuLXByb2QiLCJleHAiOjE3Njk4NDIxNzksImlhdCI6MTczODMwNjE3OX0.FXTwZ8nQKCG66xO0wMbx4Mga8SqFZcm65pq7_iMKjXPMH_h0IBHmSV2DOKQVfNbI1W9BRUCuSUwbALFgDqLrBg ``` ```json { "ok": true, "description": "Swap to list", "result": { "filtered": [ { "contractAddress": "0x765DE816845861e75A25fCA122bb6898B8B1282a", "tokenSymbol": "cUSD", "tokenDecimals": "18", "balance": "" } ] } } ``` # 4 This endpoint returns the **max FROM token only**. This is sufficient to determine whether to proceed to the next step or not and follows a similar UX to sarafu.network. It is important to check if max/tokenDecimals > 0.1 for UX purposes and to prevent swapping of dust values. ```bash # /pool/:pool/limit/:from/:to/:address > GET http://localhost:5006/api/v1/pool/0x48a953cA5cf5298bc6f6Af3C608351f537AAcb9e/limit/0x078b3a26596218507781722A4e8825BFB9570Fba/0x765DE816845861e75A25fCA122bb6898B8B1282a/0x5523058cdFfe5F3c1EaDADD5015E55C6E00fb439 > authorization: Bearer eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJwdWJsaWNLZXkiOiIweDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAiLCJzZXJ2aWNlIjp0cnVlLCJpc3MiOiJldGgtY3VzdG9kaWFsLWRldiIsInN1YiI6InNuLXByb2QiLCJleHAiOjE3Njk4NDIxNzksImlhdCI6MTczODMwNjE3OX0.FXTwZ8nQKCG66xO0wMbx4Mga8SqFZcm65pq7_iMKjXPMH_h0IBHmSV2DOKQVfNbI1W9BRUCuSUwbALFgDqLrBg ``` ```json { "ok": true, "description": "From token max limit", "result": { "max": "1339482" } } ``` # 5 Refer to `eth-custodial` docs.