CorporateBallot¶
Calls¶
attach_ballot¶
Attach a corporate ballot to the CA identified by ca_id
.
The ballot will admit votes within range
.
The ballot's metadata is provided by meta
,
which includes the ballot title, the motions, their choices, etc.
See the BallotMeta
for more.
## Arguments
- origin
is a signer that has permissions to act as an agent of ca_id.ticker
.
- ca_id
identifies the CA to attach the ballot to.
- range
specifies when voting starts and ends.
- meta
specifies the ballot's metadata as aforementioned.
- rcv
specifies whether RCV is enabled for this ballot.
# Errors
- UnauthorizedAgent
if origin
is not agent-permissioned for ticker
.
- NoSuchCA
if ca_id
does not identify an existing CA.
- CANotNotice
if the CA is not of the IssuerNotice
kind.
- StartAfterEnd
if range.start > range.end
.
- NowAfterEnd
if now > range.end
where now
is the current timestamp.
- NoRecordDate
if CA has no record date.
- RecordDateAfterStart
if date > range.start
where date
is the CA's record date.
- AlreadyExists
if there's a ballot already.
- NumberOfChoicesOverflow
if the total choice in meta
overflows usize
.
- TooLong
if any of the embedded strings in meta
are too long.
- InsufficientBalance
if the protocol fee couldn't be charged.
Attributes¶
Name | Type |
---|---|
ca_id | CAId |
range | BallotTimeRange |
meta | BallotMeta |
rcv | bool |
Python¶
call = substrate.compose_call(
'CorporateBallot', 'attach_ballot', {
'ca_id': {
'local_id': 'u32',
'ticker': '[u8; 12]',
},
'meta': {
'motions': [
{
'choices': ['Bytes'],
'info_link': 'Bytes',
'title': 'Bytes',
},
],
'title': 'Bytes',
},
'range': {
'end': 'u64',
'start': 'u64',
},
'rcv': 'bool',
}
)
change_end¶
Amend the end date of the ballot of the CA identified by ca_id
.
## Arguments
- origin
is a signer that has permissions to act as an agent of ca_id.ticker
.
- ca_id
identifies the attached ballot's CA.
- end
specifies the new end date of the ballot.
# Errors
- UnauthorizedAgent
if origin
is not agent-permissioned for ticker
.
- NoSuchBallot
if ca_id
does not identify a ballot.
- VotingAlreadyStarted
if start >= now
, where now
is the current time.
- StartAfterEnd
if start > end
.
Attributes¶
Name | Type |
---|---|
ca_id | CAId |
end | Moment |
Python¶
call = substrate.compose_call(
'CorporateBallot', 'change_end', {
'ca_id': {
'local_id': 'u32',
'ticker': '[u8; 12]',
},
'end': 'u64',
}
)
change_meta¶
Amend the metadata (title, motions, etc.) of the ballot of the CA identified by ca_id
.
## Arguments
- origin
is a signer that has permissions to act as an agent of ca_id.ticker
.
- ca_id
identifies the attached ballot's CA.
- meta
specifies the new metadata.
# Errors
- UnauthorizedAgent
if origin
is not agent-permissioned for ticker
.
- NoSuchBallot
if ca_id
does not identify a ballot.
- VotingAlreadyStarted
if start >= now
, where now
is the current time.
- NumberOfChoicesOverflow
if the total choice in meta
overflows usize
.
- TooLong
if any of the embedded strings in meta
are too long.
Attributes¶
Name | Type |
---|---|
ca_id | CAId |
meta | BallotMeta |
Python¶
call = substrate.compose_call(
'CorporateBallot', 'change_meta', {
'ca_id': {
'local_id': 'u32',
'ticker': '[u8; 12]',
},
'meta': {
'motions': [
{
'choices': ['Bytes'],
'info_link': 'Bytes',
'title': 'Bytes',
},
],
'title': 'Bytes',
},
}
)
change_rcv¶
Amend RCV support for the ballot of the CA identified by ca_id
.
## Arguments
- origin
is a signer that has permissions to act as an agent of ca_id.ticker
.
- ca_id
identifies the attached ballot's CA.
- rcv
specifies if RCV is to be supported or not.
# Errors
- UnauthorizedAgent
if origin
is not agent-permissioned for ticker
.
- NoSuchBallot
if ca_id
does not identify a ballot.
- VotingAlreadyStarted
if start >= now
, where now
is the current time.
Attributes¶
Name | Type |
---|---|
ca_id | CAId |
rcv | bool |
Python¶
call = substrate.compose_call(
'CorporateBallot', 'change_rcv', {
'ca_id': {
'local_id': 'u32',
'ticker': '[u8; 12]',
},
'rcv': 'bool',
}
)
remove_ballot¶
Remove the ballot of the CA identified by ca_id
.
## Arguments
- origin
is a signer that has permissions to act as an agent of ca_id.ticker
.
- ca_id
identifies the attached ballot's CA.
# Errors
- UnauthorizedAgent
if origin
is not agent-permissioned for ticker
.
- NoSuchBallot
if ca_id
does not identify a ballot.
- VotingAlreadyStarted
if start >= now
, where now
is the current time.
Attributes¶
Name | Type |
---|---|
ca_id | CAId |
Python¶
call = substrate.compose_call(
'CorporateBallot', 'remove_ballot', {
'ca_id': {
'local_id': 'u32',
'ticker': '[u8; 12]',
},
}
)
vote¶
Cast votes
in the ballot attached to the CA identified by ca_id
.
## Arguments
- origin
which must be a permissioned signer targeted by the CA.
- ca_id
identifies the attached ballot's CA.
- votes
specifies the balances to assign to each choice in the ballot.
The full voting power of origin
's DID may be used for each motion in the ballot.
# Errors
- NoSuchBallot
if ca_id
does not identify a ballot.
- VotingNotStarted
if the voting period hasn't commenced yet.
- VotingAlreadyEnded
if the voting period has ended.
- WrongVoteCount
if the number of choices in the ballot does not match votes.len()
.
- NoSuchCA
if ca_id
does not identify an existing CA.
- NotTargetedByCA
if the CA does not target origin
's DID.
- InsufficientVotes
if the voting power used for any motion in votes
exceeds origin
's DID's voting power.
Attributes¶
Name | Type |
---|---|
ca_id | CAId |
votes | Vec<BallotVote> |
Python¶
call = substrate.compose_call(
'CorporateBallot', 'vote', {
'ca_id': {
'local_id': 'u32',
'ticker': '[u8; 12]',
},
'votes': [
{
'fallback': (None, 'u16'),
'power': 'u128',
},
],
}
)
Events¶
Created¶
A corporate ballot was created.
(Agent DID, CA's ID, Voting start/end, Ballot metadata, RCV enabled?)
Attributes¶
Name | Type | Composition |
---|---|---|
None | IdentityId |
[u8; 32] |
None | CAId |
{'ticker': '[u8; 12]', 'local_id': 'u32'} |
None | BallotTimeRange |
{'start': 'u64', 'end': 'u64'} |
None | BallotMeta |
{'title': 'Bytes', 'motions': [{'title': 'Bytes', 'info_link': 'Bytes', 'choices': ['Bytes']}]} |
None | bool |
bool |
MetaChanged¶
A corporate ballot changed its metadata.
(Agent DID, CA's ID, New metadata)
Attributes¶
Name | Type | Composition |
---|---|---|
None | IdentityId |
[u8; 32] |
None | CAId |
{'ticker': '[u8; 12]', 'local_id': 'u32'} |
None | BallotMeta |
{'title': 'Bytes', 'motions': [{'title': 'Bytes', 'info_link': 'Bytes', 'choices': ['Bytes']}]} |
RCVChanged¶
A corporate ballot changed its RCV support.
(Agent DID, CA's ID, New support)
Attributes¶
Name | Type | Composition |
---|---|---|
None | IdentityId |
[u8; 32] |
None | CAId |
{'ticker': '[u8; 12]', 'local_id': 'u32'} |
None | bool |
bool |
RangeChanged¶
A corporate ballot changed its start/end date range.
(Agent DID, CA's ID, Voting start/end)
Attributes¶
Name | Type | Composition |
---|---|---|
None | IdentityId |
[u8; 32] |
None | CAId |
{'ticker': '[u8; 12]', 'local_id': 'u32'} |
None | BallotTimeRange |
{'start': 'u64', 'end': 'u64'} |
Removed¶
A corporate ballot was removed.
(Agent DID, CA's ID)
Attributes¶
Name | Type | Composition |
---|---|---|
None | EventDid |
[u8; 32] |
None | CAId |
{'ticker': '[u8; 12]', 'local_id': 'u32'} |
VoteCast¶
A vote was cast in a corporate ballot.
(voter DID, CAId, Votes)
Attributes¶
Name | Type | Composition |
---|---|---|
None | IdentityId |
[u8; 32] |
None | CAId |
{'ticker': '[u8; 12]', 'local_id': 'u32'} |
None | Vec<BallotVote> |
[{'power': 'u128', 'fallback': (None, 'u16')}] |
Storage functions¶
Metas¶
Metadata of a corporate ballot.
(CAId) => BallotMeta
Python¶
result = substrate.query(
'CorporateBallot', 'Metas', [
{
'local_id': 'u32',
'ticker': '[u8; 12]',
},
]
)
Return value¶
{'motions': [{'choices': ['Bytes'], 'info_link': 'Bytes', 'title': 'Bytes'}], 'title': 'Bytes'}
MotionNumChoices¶
Stores how many choices there are in each motion.
At all times, the invariant holds that motion_choices[idx]
is equal to
metas.unwrap().motions[idx].choices.len()
. That is, this is just a cache,
used to avoid fetching all the motions with their associated texts.
u16
choices should be more than enough to fit real use cases.
(CAId) => Number of choices in each motion.
Python¶
result = substrate.query(
'CorporateBallot', 'MotionNumChoices', [
{
'local_id': 'u32',
'ticker': '[u8; 12]',
},
]
)
Return value¶
['u16']
RCV¶
Is ranked choice voting (RCV) enabled for this ballot?
For an understanding of how RCV is handled, see note on BallotVote
's fallback
field.
(CAId) => bool
Python¶
result = substrate.query(
'CorporateBallot', 'RCV', [
{
'local_id': 'u32',
'ticker': '[u8; 12]',
},
]
)
Return value¶
'bool'
Results¶
Stores the total vote tally on each choice.
RCV is not accounted for, as there are too many wants to interpret the graph, and because it would not be efficient.
(CAId) => [current vote weights]
Python¶
result = substrate.query(
'CorporateBallot', 'Results', [
{
'local_id': 'u32',
'ticker': '[u8; 12]',
},
]
)
Return value¶
['u128']
TimeRanges¶
Time details of a corporate ballot associated with a CA. The timestamps denote when voting starts and stops.
(CAId) => BallotTimeRange
Python¶
result = substrate.query(
'CorporateBallot', 'TimeRanges', [
{
'local_id': 'u32',
'ticker': '[u8; 12]',
},
]
)
Return value¶
{'end': 'u64', 'start': 'u64'}
Votes¶
Stores each DID's votes in a given ballot.
See the documentation of BallotVote
for notes on semantics.
(CAId) => (DID) => [vote weight]
User must enter 0 vote weight if they don't want to vote for a choice.
Python¶
result = substrate.query(
'CorporateBallot', 'Votes', [
{
'local_id': 'u32',
'ticker': '[u8; 12]',
},
'[u8; 32]',
]
)
Return value¶
[{'fallback': (None, 'u16'), 'power': 'u128'}]
Errors¶
AlreadyExists¶
A corporate ballot already exists for this CA.
CANotNotice¶
A corporate ballot was made for a non IssuerNotice
CA.
InsufficientVotes¶
Voting power used by a DID on a motion exceeds that which is available to them.
NoSuchBallot¶
A corporate ballot doesn't exist for this CA.
NoSuchRCVFallback¶
The RCV fallback of some choice does not exist.
NowAfterEnd¶
A corporate ballot's end time was strictly before the current time.
NumberOfChoicesOverflow¶
If some motion in a corporate ballot has more choices than would fit in u16
.
RCVNotAllowed¶
RCV is not allowed for this ballot.
RCVSelfCycle¶
The RCV fallback points to the origin choice.
StartAfterEnd¶
A corporate ballot's start time was strictly after the ballot's end.
VotingAlreadyEnded¶
Voting ended already.
VotingAlreadyStarted¶
Voting started already. Amending a ballot is no longer possible.
VotingNotStarted¶
Voting hasn't started yet.
WrongVoteCount¶
Provided list of balances does not match the total number of choices.