Create api docs for Polkassembly integration

[wliyongfeng]

The high priority apis includes:

• Get the proposal list for one space, including active, pending, closed ones.
• Creating a proposal, we should provide fields required, check conditions.
• Get the proposal detail, including title, content, votes, comments, configurations(time period, snapshot height, strategies).
• Get the proposal real-time voting status/result for each strategies.

For fast collaboration, we can first leave the docs on this issue. @hyifeng

[hyifeng]

API Endpoints for testing

• https://review.opensquare.io
• https://test.opensquare.io

1. Get the proposal list for one space, including active, pending, closed ones.

GET /api/[spaceName]/proposals?page=[pageIndex]&page_size=[pageSize]

Parameters:
  - spaceName: Get proposals for the space (polkadot / kusama / karura / khala)
  - pageIndex: The pagination index from 1 to N
  - pageSize: The items count per page

Response:

{
  "items": [
    {
       "_id": "619db5558edbaeb5e1620166",
      "space": "polkadot",
      "title": "The proposal title",
      "content": "This is the proposal description",
      "contentType": "markdown",
      "choiceType": "single",
      "choices": [
        "Aye",
        "Nay"
      ],
      "startDate": 1637683200000,
      "endDate": 1638201600000,
      "snapshotHeight": 7837243,
      "weightStrategy": [
        "balance-of",
        "quadratic-balance-of"
      ],
      "data": {
        "space": "polkadot",
        "title": "The proposal title",
        "content": "This is the proposal description",
        "contentType": "markdown",
        "choiceType": "single",
        "choices": [
          "Aye",
          "Nay"
        ],
        "startDate": 1637683200000,
        "endDate": 1638201600000,
        "snapshotHeight": 7837243,
        "version": "1",
        "timestamp": 1637725521
      },
      "address": "13d8i62igrsVw2bbRBzMtg7fH298n8exz7Y8y1Ty4K5bFuzf",
      "signature": "0x8a6eb3a9eaceed5a1d3b1026c568d924ce79e887cda1b62cf2ea496e187771648710402f301f01874f0720f4eec327f33c74e687c2e659dd6df039bde72cb489",
      "lastActivityAt": "2021-11-24T03:45:25.619Z",
      "createdAt": "2021-11-24T03:45:25.041Z",
      "updatedAt": "2021-11-24T03:45:25.041Z",
      "cid": "QmcPcJ1mLghjKB9BfxUKJcp8kkfGFWqc9MZEf9mWVbfyvE",
      "pinHash": "QmcPcJ1mLghjKB9BfxUKJcp8kkfGFWqc9MZEf9mWVbfyvE",
      "status": "active"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 10
}

Fields explanation:

Fields	Explanations
_id	The primary key of the proposal
cid	The proposal unique index
space	The name of the space to which the proposal belongs
title	The proposal title
content	The proposal's detail description
contentType	The proposal description content format, currently only "markdown"
choiceType	The proposal voting method, single choice or multiple choices
choices	A range of options that voters can vote for
startDate	Start time for voting
endDate	End time for voting
snapshotHeight	The voting weight will be calculated based on the snapshot height of the blockchain
weightStrategy	Proposal voting weight strategies
data	The raw data that was post to create this proposal
address	The proposal creator address
signature	The signature of the raw post data, signed by proposal creator address
lastActivityAt	Last action time of the proposal, including creating, updating, voting or comment actions
createdAt	Proposal create time
updatedAt	Proposal edit time
pinHash	Proposal IPFS storage pin hash
status	Proposal status by startDate and endDate, it can be "pending", "active", "closed"

2. Create a proposal

POST /api/[spaceName]/proposals

Request body:

{
  "data": {
    "space": "polkadot",
    "title": "The title",
    "content": "The content",
    "contentType": "markdown",
    "choiceType": "single",
    "choices": [
      "Aye",
      "Nay"
    ],
    "startDate": 1637683200000,
    "endDate": 1638201600000,
    "snapshotHeight": 7838239,
    "version": "1",
    "timestamp": 1637731522
  },
  "address": "13d8i62igrsVw2bbRBzMtg7fH298n8exz7Y8y1Ty4K5bFuzf",
  "signature": "0x2c662f6676afb63bf156c073275b43d5320ca7e05885360308f21c5b7352076e5b76395d6e98360868ea07bf68f49b735988995640dd16c99e21856563376d8e"
}

Fields explanation:

Fields	Explanations
data.space	The name of the space to which the proposal belongs
data.title	The proposal title
data.content	The proposal's detail description
data.contentType	The proposal description content format, currently only "markdown"
data.choiceType	The proposal voting method, single choice or multiple choices
data.choices	A range of options that voters can vote for
data.startDate	Start time for voting
data.endDate	End time for voting
data.snapshotHeight	The voting weight will be calculated based on the snapshot height of the blockchain
data.version	The data structure version
data.timestamp	Proposal create time
address	The proposal creator address
signature	The signature of the data message, signed by proposal creator address (data message = JSON.stringify(data))

Response:

{
  "cid": "QmNRBRpQmdQRyDEkUdwWXkrE1wKyA5muXsVTWVG9cfobJh",
}

Fields explanation:

Fields	Explanations
cid	The proposal unique index

3. Get proposal details

GET /api/[spaceName]/proposal/[id]

Parameters:
  - spaceName: Get proposal for the space (polkadot / kusama / karura / khala)
  - id: The "_id" or "cid" of the proposal

Response

{
  "_id": "619db5558edbaeb5e1620166",
  "space": "polkadot",
  "title": "The proposal title",
  "content": "This is the proposal description",
  "contentType": "markdown",
  "choiceType": "single",
  "choices": [
    "Aye",
    "Nay"
  ],
  "startDate": 1637683200000,
  "endDate": 1638201600000,
  "snapshotHeight": 7837243,
  "weightStrategy": [
    "balance-of",
    "quadratic-balance-of"
  ],
  "data": {
    "space": "polkadot",
    "title": "The proposal title",
    "content": "This is the proposal description",
    "contentType": "markdown",
    "choiceType": "single",
    "choices": [
      "Aye",
      "Nay"
    ],
    "startDate": 1637683200000,
    "endDate": 1638201600000,
    "snapshotHeight": 7837243,
    "version": "1",
    "timestamp": 1637725521
  },
  "address": "13d8i62igrsVw2bbRBzMtg7fH298n8exz7Y8y1Ty4K5bFuzf",
  "signature": "0x8a6eb3a9eaceed5a1d3b1026c568d924ce79e887cda1b62cf2ea496e187771648710402f301f01874f0720f4eec327f33c74e687c2e659dd6df039bde72cb489",
  "lastActivityAt": "2021-11-24T03:45:25.619Z",
  "createdAt": "2021-11-24T03:45:25.041Z",
  "updatedAt": "2021-11-24T03:45:25.041Z",
  "cid": "QmcPcJ1mLghjKB9BfxUKJcp8kkfGFWqc9MZEf9mWVbfyvE",
  "pinHash": "QmcPcJ1mLghjKB9BfxUKJcp8kkfGFWqc9MZEf9mWVbfyvE",
  "votesCount": 2,
  "votedWeights": {
    "balanceOf": "22200000000000",
    "quadraticBalanceOf": "666333249958"
  },
  "status": "active"
}

Fields explanation:

Fields	Explanations
_id	The primary key of the proposal
cid	The proposal unique index
space	The name of the space to which the proposal belongs
title	The proposal title
content	The proposal's detail description
contentType	The proposal description content format, currently only "markdown"
choiceType	The proposal voting method, single choice or multiple choices
choices	A range of options that voters can vote for
startDate	Start time for voting
endDate	End time for voting
snapshotHeight	The voting weight will be calculated based on the snapshot height of the blockchain
weightStrategy	Proposal voting weight strategies
data	The raw data that was post to create this proposal
address	The proposal creator address
signature	The signature of the raw post data, signed by address
lastActivityAt	Last action time of the proposal, including creating, updating, voting or comment actions
createdAt	Proposal create time
updatedAt	Proposal edit time
pinHash	Proposal IPFS storage pin hash
votesCount	The current total votes
votedWeights	The weight of the current total votes in different strategies
status	Proposal status by startDate and endDate, it can be "pending", "active", "closed"

4. Get the list of current votes of a proposal

GET /api/[spaceName]/proposals/[proposalCid]/votes?page=[pageIndex]&page_size=[pageSize]

Parameters:
  - spaceName: Get proposals for the space (polkadot / kusama / karura / khala)
  - proposalCid: The proposal unique index, which is proposal "cid"
  - pageIndex: The pagination index from 1 to N
  - pageSize: The items count per page

Response

{
  "items": [
    {
      "_id": "619dd7a4bd49f05dc7544802",
      "proposal": "619dccc78edbaeb5e1620167",
      "voter": "13d8i62igrsVw2bbRBzMtg7fH298n8exz7Y8y1Ty4K5bFuzf",
      "address": "13d8i62igrsVw2bbRBzMtg7fH298n8exz7Y8y1Ty4K5bFuzf",
      "choice": "Aye",
      "cid": "QmcDGZFRSd4eYzXZ5eStrTHZbk7tPvaKvqWVZjWRavyLcV",
      "createdAt": "2021-11-24T06:11:47.908Z",
      "data": {
        "proposalCid": "QmNRBRpQmdQRyDEkUdwWXkrE1wKyA5muXsVTWVG9cfobJh",
        "choice": "Aye",
        "remark": "Sample remark text",
        "version": "1",
        "timestamp": 1637734301
      },
      "pinHash": "QmcDGZFRSd4eYzXZ5eStrTHZbk7tPvaKvqWVZjWRavyLcV",
      "remark": "Sample remark text",
      "signature": "0x6aa2d2497220a1e6a04c50877021757e5547eab7e229a4d0815eaf5b6ba8ef1139c5848742b1a3bf7f0cf8e89d0b54f18c61b9ec5c04e42f683e6e0ad8a96c84",
      "updatedAt": "2021-11-24T06:11:47.908Z",
      "weights": {
        "balanceOf": "11100000000000",
        "quadraticBalanceOf": "333166624979"
      }
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 10
}

Fields explanation:

Fields	Explanations
_id	The primary key of the vote
cid	The unique index of the vote
proposal	The primary key of the associated proposal
voter	The voter address. When using proxy voting, it is different from the address of vote creator, otherwise the same
choice	The vote choice
remark	The remark
data	The raw data that was post to create this vote
address	The address of vote creator
signature	The signature of the raw post data, signed by vote creator address
createdAt	Vote create time
pinHash	Vote IPFS storage pin hash
weights	The weight of the vote in different strategies

5. Get the Voting statistics of a proposal

GET /api/[spaceName]/proposals/[proposalCid]/stats

Parameters:
  - spaceName: Get proposals for the space (polkadot / kusama / karura / khala)
  - proposalCid: The proposal unique index, which is proposal "cid"

Response:

Calculate the sum of weights for each proposal choice separately.

[
  {
    "choice": "Aye",
    "balanceOf": "11100000000000",
    "quadraticBalanceOf": "333166624979"
  },
  {
    "choice": "Nay",
    "balanceOf": "11100000000000",
    "quadraticBalanceOf": "333166624979"
  },
]