joystream/query-node/schemas/council.graphql

# TODO:
# - do we need some fulltext search for council/election?

# workaround for https://github.com/Joystream/hydra/issues/434
type VariantNone @variant {
  _phantom: Int
}

################### Council ####################################################

type CouncilStageUpdate @entity {
  "The new stage council got into."
  stage: CouncilStage!

  "Block number at which change happened."
  changedAt: BigInt!

  "Council term during which the update happened (if any)."
  electedCouncil: ElectedCouncil

  "Election not completed due to insufficient candidates or winners."
  electionProblem: ElectionProblem
}

type CouncilStageAnnouncing @variant {
  "Number of candidates aspiring to be elected as council members."
  candidatesCount: BigInt!
}

type CouncilStageElection @variant {
  "Number of candidates aspiring to be elected as council members."
  candidatesCount: BigInt!
}

type CouncilStageIdle @variant {
  # no properties

  # TODO: remove me - variant needs to have at least 1 property now
  dummy: Int
}

union CouncilStage = CouncilStageAnnouncing | CouncilStageElection | CouncilStageIdle | VariantNone

enum ElectionProblem {
  NOT_ENOUGH_CANDIDATES
  NEW_COUNCIL_NOT_ELECTED
}

type Candidate @entity {
  "Account used for staking currency needed for the candidacy."
  stakingAccountId: String!

  "Account that will receive rewards if candidate's elected to the council."
  rewardAccountId: String!

  "Candidate's membership."
  member: Membership!

  "Election cycle"
  electionRound: ElectionRound!

  "Stake locked for the candidacy."
  stake: BigInt!

  "Reflects if the stake is still locked for candidacy or has been already released by the member."
  stakeLocked: Boolean!

  "Reflects if the candidacy was withdrawn before voting started."
  candidacyWithdrawn: Boolean!

  "Sum of power of all votes received."
  votePower: BigInt!

  "The metadata contained in note."
  noteMetadata: CandidacyNoteMetadata!

  "Votes recieved in referendums by this member."
  votesRecieved: [CastVote!]! @derivedFrom(field: "voteFor")
}

type CouncilMember @entity {
  "Runtime council member id"
  id: ID!

  "Account used for staking currency for council membership."
  stakingAccountId: String!

  "Account that will receive used for reward currency for council membership."
  rewardAccountId: String!

  "Council member's membership."
  member: Membership!

  "Stake used for the council membership."
  stake: BigInt!

  "Block number in which council member recieved the last reward payment."
  lastPaymentBlock: BigInt!

  "Reward amount that should have been paid but couldn't be paid off due to insufficient budget."
  unpaidReward: BigInt!

  "Amount of reward collected by this council member so far."
  accumulatedReward: BigInt!

  electedInCouncil: ElectedCouncil!
}

type CandidacyNoteMetadata @entity {
  "Candidacy header text."
  header: String

  "Candidate program in form of bullet points."
  bulletPoints: [String!]!

  "Image uri of candidate's banner."
  bannerImageUri: String

  "Candidacy description (Markdown-formatted)."
  description: String
}

################### Referendum #################################################

# This section (ReferendumStage*) is not useful before referencing variant is solved.
# See commented reference in ElectionRound, for example.
# Uncomment after solving the issue or delete if it can't be solved or is not needed
# in the future.
#
#type ReferendumStageInactive @variant {
#  # no properties
#
#  # TODO: remove me - variant needs to have at least 1 property now
#  dummy: Int
#}
#
#type ReferendumStageVoting @variant {
#  "Block in which referendum started."
#  started: BigInt!
#
#  "Target number of winners."
#  winningTargetCount: BigInt!
#
#  "Index of current election"
#  electionRound: ElectionRound!
#}
#
#type ReferendumStageRevealing @variant {
#  "Block in which referendum started"
#  started: BigInt!
#
#  "Target number of winners"
#  winningTargetCount: BigInt!
#
#  "Intermediate winning options"
#  intermediateWinners: [ReferendumStageRevealingOptionResult!]!
#
#  "Index of current election"
#  electionRound: ElectionRound!
#}

type ReferendumStageRevealingOptionResult @entity {
  "Member that received votes."
  option: Membership!

  "Sum of votes' power received."
  votePower: BigInt!

  # TODO: reference variant (how?)
  #referendumRevealingStages: [ReferendumStageRevealing!]! @derivedFrom(field: "intermediateWinners")

  "Election round."
  electionRound: ElectionRound!

  "Event that concluded the referendum."
  referendumFinishedEvent: ReferendumFinishedEvent!
}

# TODO: this maybe needs to be @entity - so it's saved in db
#union ReferendumStage = ReferendumStageInactive | ReferendumStageVoting | ReferendumStageRevealing | VariantNone

type CastVote @entity {
  "Hashed vote that was casted before being revealed. Hex format."
  commitment: String!

  "Election round."
  electionRound: ElectionRound!

  "Stake used to back up the vote."
  stake: BigInt!

  "Reflects if the stake is still locked for candidacy or has been already released by the member."
  stakeLocked: Boolean!

  "Account that cast the vote."
  castBy: String!

  "Member receiving the vote."
  voteFor: Candidate

  "Vote's power."
  votePower: BigInt!
}

################### Derived ####################################################

type ElectedCouncil @entity {
  "Members that were elected to the council."
  councilMembers: [CouncilMember!]! @derivedFrom(field: "electedInCouncil")

  "Changes to council status that were made during it's reign."
  updates: [CouncilStageUpdate!]! @derivedFrom(field: "electedCouncil")

  "Block number at which the council was elected."
  electedAtBlock: Int!

  "Block number at which the council reign ended and a new council was elected."
  endedAtBlock: Int

  # it might seem that derived field is wrongly set to `nextElectedCouncil`, but that's how it should be
  "Elections held before the council was rightfully elected."
  #councilElections: [ElectionRound!]! @derivedFrom(field: "electedCouncil")
  councilElections: [ElectionRound!]! @derivedFrom(field: "nextElectedCouncil")

  # it might seem that derived field is wrongly set to `electedCouncil`, but that's how it should be
  "Elections held before the next council was or will be rightfully elected."
  #nextCouncilElections: [ElectionRound!]! @derivedFrom(field: "nextElectedCouncil")
  nextCouncilElections: [ElectionRound!]! @derivedFrom(field: "electedCouncil")

  "Sign if council is already resigned."
  isResigned: Boolean!
}

type ElectionRound @entity {
  "Election cycle ID."
  cycleId: Int!

  "Sign if election has already finished."
  isFinished: Boolean!

  "Vote cast in the election round."
  castVotes: [CastVote!]! @derivedFrom(field: "electionRound")

  # TODO: reference variant (how?)
  #referendumStageVoting: ReferendumStage @derivedFrom(field: "cycleId")
  #referendumStageRevealing: ReferendumStage @derivedFrom(field: "cycleId")

  "Council that is ruling during the election."
  electedCouncil: ElectedCouncil!

  "Council that was elected in this election round."
  nextElectedCouncil: ElectedCouncil

  "Candidates in this election round."
  candidates: [Candidate!]! @derivedFrom(field: "electionRound")
}

# Not yet sure if this will be needed by apps using query node.
#
#type Budget @entity {
#  "Block number at which the next rewards will be paid."
#  nextRewardPaymentsAt: BigInt!
#}
#
#type BudgetPayment @entity {
#  "Block number at which the payment was done."
#  paidAtBlock: Int!
#
#  "Member that was paid."
#  member: Membership!
#
#  "Account that received the payment"
#  account: String!
#
#  "Amount that was paid."
#  amount: BigInt!
#
#  "Amount that couldn't be paid due to insufficient council budget's balance."
#  unpaidAmount: BigInt!
#}