Steward Report Card API

Steward Report Card API

This document contains the specification and implementation details for the Gitcoin Stewards API.
 
The API should return the following fields:
steward_since Date – date the steward became a steward
forum_posts_count Int - number of posts in discourse
delegators_count Int - number of addresses delegated gtc
voting_power Float - % of total gtc in steward's delegation
vote_participation Float - % of proposals the steward voted in
score Int (out of 100) - calculated score using above data points
 
Assume the following variables:
gtc_address Address of GTC voter
profile.handle Discourse handle
profile.bio Bio address
 
Data Points
steward_since
Bio address has the following format:
https://gov.gitcoin.co/t/introducing-stewards-governance/41/2
 
The corresponding API request takes this format.
 
Docs for this request: https://docs.discourse.org/#tag/Topics/paths/~1t~1{id}~1posts.json/get
GET [discourse api url]/t/41/posts.json
Headers:
Api-Key Discourse API Key
Api-Username Discourse username associated with API Key ("system"?)
Content-Type application/json
 
Request Body: 
{
	"post_ids": [2]
}
 
This will return an object with the following structure
{
	"post_stream": {
		"posts": [
			{
				...
				"id": 2,
				"created_at": "date_string"
				...
			}
		]
	}
}
 
Use post_stream.posts[0].created_at as the date the steward became a steward and assign to steward_since
 
forum_posts_count
 
Docs: https://docs.discourse.org/#tag/Users/paths/~1admin~1users~1{id}.json/get
 
Request format:
GET https://{defaultHost}/u/{profile.handle}.json
 
Headers:
Api-Key Discourse API Key
Api-Username Discourse username associated with API Key ("system"?)
Content-Type application/json
 
This request returns an object with the format:
{
	"user":	{
		...
		"id": 2,
		"username": "{profile.handle}",
		"post_count": 0
		...
	}
}
 
Use user.post_count as the value for forum_posts_count
 
 
delegators_count
Graph URL: https://api.thegraph.com/subgraphs/name/withtally/protocol-gitcoin-bravo-v2
 
query:
query ($voterAddress: String!) {
  histories {
    totalSupply
  },
  account(id: $voterAddress) {
    id
    votes
    tokenBalance
    ballotsCastCount
    proposalsProposedCount
    percentageOfTotalVotingPower // <-- try using this for voting_power
    frequencyOfParticipationTotal
    delegationsCurrentlyReceivedCount // <--- we want this
    frequencyOfParticipationAsActiveVoter
  }
  delegators: accounts(orderBy: tokenBalance, orderDirection: desc, where: {delegatingTo: $voterAddress}){
    id
    votes
    tokenBalance
    ballotsCastCount
    proposalsProposedCount
    percentageOfTotalVotingPower
    frequencyOfParticipationTotal
    delegationsCurrentlyReceivedCount
    frequencyOfParticipationAsActiveVoter
  }
}
 
Assign query.account.delegationsCurrentlyReceivedCount to delegate_count
 
voting_power
FIRST METHOD: use response from delegators_count (above) and get query.account.percentageOfTotalVotingPower
 
If that doesn't work, SECOND METHOD:
Docs: https://swagger.boardroom.info/#/voter/getVoter
 
Request format:
GET https://api.boardroom.info/v1/voters/{gtc_address}
 
Headers:
Content-Type application/json
 
This request returns an object with the format:
{
  "data": {
    "address": "{gtc_address}",
    "firstVoteCast": 1625066741,
    "lastVoteCast": 1625066741,
    "totalVotesCast": 1, 
    "protocols": [
      {
        "protocol": "gitcoin",
        "totalVotesCast": 1, // <--
 
Use data.protocols.find(p => p.protocol == 'gitcoin').lastCastPower divided by the GTC.totalSupply() times 100 as the value for voting_power
 
vote_participation
 
Docs: https://swagger.boardroom.info/#/protocol/getProtocolDetails
 
Request format:
GET https://api.boardroom.info/v1/protocols/gitcoin
 
Headers:
Content-Type application/json
 
This request returns an object with the format:
{
  "data": {
    "cname": "gitcoin",
    "name": "Gitcoin",
    "totalProposals": 28, // <-- this is the value we want
    "totalVotes": 1270,
    "uniqueVoters": 733,
    "icons": [
      {
        "adapter": "default",
        "size": "thumb",
        "url": "https://assets.coingecko.com/coins/images/12645/thumb/AAVE.png?1601374110"
      },
      {
        "adapter": "default",
        "size": "small",
        "url": "https://assets.coingecko.com/coins/images/12645/small/AAVE.png?1601374110"
      },
      {
        "adapter": "default",
        "size": "large",
        "url": "https://assets.coingecko.com/coins/images/12645/large/AAVE.png?1601374110"
      }
    ],
    "tokens": [
      {
        "adapter": "default",
        "symbol": "aave",
        "network": "ethereum",
        "contractAddress": "0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9",
        "marketPrices": [
          {
            "currency": "usd",
            "price": 384.14
          }
        ]
      }
    ]
  }
}
 
from voting_power request:
let userVotesCast := data.protocols.find(p => p.protocol == 'gitcoin').totalVotesCast
from this request
let totalVotes := data.totalProposals
 
Assign userVotesCast * 100 / totalVotes to vote_participation
 
 
Steward Report Card API

Steward Report Card API

This document contains the specification and implementation details for the Gitcoin Stewards API.
 
The API should return the following fields:
steward_since Date – date the steward became a steward
forum_posts_count Int - number of posts in discourse
delegators_count Int - number of addresses delegated gtc
voting_power Float - % of total gtc in steward's delegation
vote_participation Float - % of proposals the steward voted in
score Int (out of 100) - calculated score using above data points
 
Assume the following variables:
gtc_address Address of GTC voter
profile.handle Discourse handle
profile.bio Bio address
 
Data Points
steward_since
Bio address has the following format:
https://gov.gitcoin.co/t/introducing-stewards-governance/41/2
 
The corresponding API request takes this format.
 
Docs for this request: https://docs.discourse.org/#tag/Topics/paths/~1t~1{id}~1posts.json/get
GET [discourse api url]/t/41/posts.json
Headers:
Api-Key Discourse API Key
Api-Username Discourse username associated with API Key ("system"?)
Content-Type application/json
 
Request Body: 
{
	"post_ids": [2]
}
 
This will return an object with the following structure
{
	"post_stream": {
		"posts": [
			{
				...
				"id": 2,
				"created_at": "date_string"
				...
			}
		]
	}
}
 
Use post_stream.posts[0].created_at as the date the steward became a steward and assign to steward_since
 
forum_posts_count
 
Docs: https://docs.discourse.org/#tag/Users/paths/~1admin~1users~1{id}.json/get
 
Request format:
GET https://{defaultHost}/u/{profile.handle}.json
 
Headers:
Api-Key Discourse API Key
Api-Username Discourse username associated with API Key ("system"?)
Content-Type application/json
 
This request returns an object with the format:
{
	"user":	{
		...
		"id": 2,
		"username": "{profile.handle}",
		"post_count": 0
		...
	}
}
 
Use user.post_count as the value for forum_posts_count
 
 
delegators_count
Graph URL: https://api.thegraph.com/subgraphs/name/withtally/protocol-gitcoin-bravo-v2
 
query:
query ($voterAddress: String!) {
  histories {
    totalSupply
  },
  account(id: $voterAddress) {
    id
    votes
    tokenBalance
    ballotsCastCount
    proposalsProposedCount
    percentageOfTotalVotingPower // <-- try using this for voting_power
    frequencyOfParticipationTotal
    delegationsCurrentlyReceivedCount // <--- we want this
    frequencyOfParticipationAsActiveVoter
  }
  delegators: accounts(orderBy: tokenBalance, orderDirection: desc, where: {delegatingTo: $voterAddress}){
    id
    votes
    tokenBalance
    ballotsCastCount
    proposalsProposedCount
    percentageOfTotalVotingPower
    frequencyOfParticipationTotal
    delegationsCurrentlyReceivedCount
    frequencyOfParticipationAsActiveVoter
  }
}
 
Assign query.account.delegationsCurrentlyReceivedCount to delegate_count
 
voting_power
FIRST METHOD: use response from delegators_count (above) and get query.account.percentageOfTotalVotingPower
 
If that doesn't work, SECOND METHOD:
Docs: https://swagger.boardroom.info/#/voter/getVoter
 
Request format:
GET https://api.boardroom.info/v1/voters/{gtc_address}
 
Headers:
Content-Type application/json
 
This request returns an object with the format:
{
  "data": {
    "address": "{gtc_address}",
    "firstVoteCast": 1625066741,
    "lastVoteCast": 1625066741,
    "totalVotesCast": 1, 
    "protocols": [
      {
        "protocol": "gitcoin",
        "totalVotesCast": 1, // <--
 
Use data.protocols.find(p => p.protocol == 'gitcoin').lastCastPower divided by the GTC.totalSupply() times 100 as the value for voting_power
 
vote_participation
 
Docs: https://swagger.boardroom.info/#/protocol/getProtocolDetails
 
Request format:
GET https://api.boardroom.info/v1/protocols/gitcoin
 
Headers:
Content-Type application/json
 
This request returns an object with the format:
{
  "data": {
    "cname": "gitcoin",
    "name": "Gitcoin",
    "totalProposals": 28, // <-- this is the value we want
    "totalVotes": 1270,
    "uniqueVoters": 733,
    "icons": [
      {
        "adapter": "default",
        "size": "thumb",
        "url": "https://assets.coingecko.com/coins/images/12645/thumb/AAVE.png?1601374110"
      },
      {
        "adapter": "default",
        "size": "small",
        "url": "https://assets.coingecko.com/coins/images/12645/small/AAVE.png?1601374110"
      },
      {
        "adapter": "default",
        "size": "large",
        "url": "https://assets.coingecko.com/coins/images/12645/large/AAVE.png?1601374110"
      }
    ],
    "tokens": [
      {
        "adapter": "default",
        "symbol": "aave",
        "network": "ethereum",
        "contractAddress": "0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9",
        "marketPrices": [
          {
            "currency": "usd",
            "price": 384.14
          }
        ]
      }
    ]
  }
}
 
from voting_power request:
let userVotesCast := data.protocols.find(p => p.protocol == 'gitcoin').totalVotesCast
from this request
let totalVotes := data.totalProposals
 
Assign userVotesCast * 100 / totalVotes to vote_participation