# Trust API for the DeFi Portal DApp

The DeFi Portal DApp shows the user a list of DeFi DApps/protocols of different categories.

The user is identified by their Ethereum address, and the DApp uses the Trust API to show them which of the addresses that they interacted with used which DeFi protocols and how.

For example, it might show "3 of the addresses you recently interacted with provided liquidity on Uniswap."

In a later version, we might provide a link in the recommendation text to show more details, e.g. in a popup canvas. This might include which addresses that were, the transaction dates, and which pools.

## Posting entities

Entities in the Trust API for the DeFi Portal usecase are
1. Ethereum addresses, using entity type "address" and `ids` property <br/> ```{ address: <address> }```
2. DeFi Protocols, using entity type "defi" and `ids` property <br/> ```{ contract: <Main smart contract address> }```

_Example body for_ `POST localhost/entity` posting an address:

{
  "type": "address",
  "name": "591..286",
  "ids": { "address": "0xe0542ec7927b578d122652cd0432cea9c5f314b2" }
}

_Example body for_ `POST localhost/entity` posting a DeFi protocol:

{
  "type": "DeFiProtocol",
  "name": "Uniswap V2",
  "ids": { 
      "contract": "UniswapV2" 
  },
  "image": "https://info.uniswap.org/static/media/logo_white.edb44e56.svg",
  "properties": { 
    "category": "DEX", 
    "description": "Automated market maker with token pair routing."
  }
}

## Posting relationships

In the first version, the only relationships posted to the Trust API are the ones retrieved by the [defi-portal-scanner](https://github.com/utu-protocol/defi-portal-scanner). They use relationship type `"interaction"` and additional properties such as `action`, `txId`, `timestamp`, `tokenPair`, `tokenFrom` and `tokenTo` which might be used by the DeFi Portal-specific feedback renderer.

_Example body for_ `POST localhost/relationship` posting a `send` transaction:

{
  "type": "interaction",
  "sourceCriteria": { 
    "type": "address", 
    "ids": { "address": "0xe7448fec13f5c7e2a7c5e2f3634cf4ee8273c1db" }
  },
  "targetCriteria": { 
    "type": "DefiProtocol", 
    "ids": { "address": "UniswapV2" }
  },
  "properties": {
    "action": "Transfer", 
    "txId": "0xbfc54fae61f6bcb144ff5003c07048c835da4ff49bd67d66f1e0baeaf56f925e",
    "timestamp": "2020-10-16T06:55:21+0000",
    "token": "ETH",
    "contract": "0x123",
    "contract_name": "",
  } 
}

_Example body for_ `POST localhost/relationship` posting a Uniswap swap:

{
  "type": "interaction",
  "sourceCriteria": { 
    "type": "address", 
    "ids": { "address": "0xe0542ec7927b578d122652cd0432cea9c5f314b2" }
  },
  "targetCriteria": { 
    "type": "DEX", 
    "ids": { "contract": "0x7a250d5630b4cf539739df2c5dacb4c659f2488d" }
  },
  "properties": {
    "action": "swap", 
    "txId": "0x591de69dd40356594f15e1c487a58b262e7de3c72fcf768ec414ce120f4b5286",
    "timestamp": "2020-10-22T08:36:12+0000",
    "tokenPair": "ETH-UTU",
    "tokenFrom": "ETH",
    "tokenTo": "UTU"
  } 
}

_Example body for_ `POST localhost/relationship` adding liquidity:

{
  "type": "interaction",
  "sourceCriteria": { 
    "type": "address", 
    "ids": { "address": "0xe0542ec7927b578d122652cd0432cea9c5f314b2" }
  },
  "targetCriteria": { 
    "type": "DeFi-Protocol", 
    "ids": { "contract": "0x7a250d5630b4cf539739df2c5dacb4c659f2488d" }
  },
  "properties": {
    "action": "add_liquidity", 
    "txId": "0x591de69dd40356594f15e1c487a58b262e7de3c72fcf768ec414ce120f4b5286",
    "timestamp": "2020-10-22T08:36:12+0000",
    "tokenPair": "ETH-UTU"
  } 
}

## Getting feedback on DeFi protocols

The `GET /ranking` service is used to retrieve UTU recommendations (or more generally feedback) for entities, in this use-case for DeFi protocols. It returns a ranked (sorted) list of DeFi protocols of a certain type.

The result set might further be constrained by providing a value for the `targetCriterias` parameter, but this probably won't be used by the DeFi Portal.

_Example query for_ `GET localhost/ranking` for DeFi-Protocols (here written as json, a real request would need to be transformed to query parameters, stringifying the inner json objects):

 { 
    "type": "Address", 
    "ids": { "address": "0xe0542ec7927b578d122652cd0432cea9c5f314b2" }
 }

> Note: the actual URL should look like `GET https://api.ututrust.com/ranking?sourceCriteria=${URL_ENCODED_JSON}&targetType=DeFiProtocol`

which might lead to a response like this:

{
  "status": "success",
  "result": [
    {
      "entity": {
        "name": "Compound",
        "type": "DeFiProtocol"
      },
      "relationshipPaths": [
        [
          {
            "targetEntity": {
              "name": "Compound",
              "type": "DeFiProtocol"
            },
            "relationship": {
              "inverse": false,
              "type": "interaction"
            }
          }
        ]
      ],
      "summaryText": "You used this DeFiProtocol",
      "summaryImages": []
    },
    {
      "entity": {
        "name": "MakerDAO",
        "type": "DeFiProtocol"
      },
      "relationshipPaths": [
        [
          {
            "targetEntity": {
              "name": "MakerDAO",
              "type": "DeFiProtocol"
            },
            "relationship": {
              "inverse": false,
              "type": "interaction"
            }
          }
        ]
      ],
      "summaryText": "You falseused this DeFiProtocol",
      "summaryImages": []
    },
    {
      "entity": {
        "name": "Uniswap V2",
        "type": "DeFiProtocol"
      },
      "relationshipPaths": [],
      "summaryText": null,
      "summaryImages": []
    }
  ]
}