Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion book/src/contract-keywords/contested.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ The fund, the windows, the tallies and the special case of moderation elections
- A document type has at most one contested index, and no other unique index beside it (`ContestedUniqueIndexWithUniqueIndexError`, 10249).
- `resolution` is present and is `0` or `1`; `1` is refused before protocol version 14.
- `fieldMatches`, when present, holds at least one entry, and each `regexPattern` is a valid regular expression (`RegexError`, 10247).
- From protocol version 15, the contest is decided by the index values, so that two documents with the same values are both contested or both ordinary: every `fieldMatches` field is a property of the index, and a match on a string property that may be empty (no `minLength` of at least 1) treats `""` and `"\0"` alike, since the two share one index key (`InvalidContractStructure`, 10231). Otherwise an ordinary document could take the values of a contested one, and the contest would have nothing left to award. A contract registered earlier keeps its contest, but can no longer be updated, since an update is checked like a registration; while such a contest is live, a create outside it with the same index values is refused (`DuplicateUniqueIndexError`).
- From protocol version 15, the contest is decided by the index values, so that two documents with the same values are both contested or both ordinary: every `fieldMatches` field is a property of the index, and a match on a string property that may be empty (no `minLength` of at least 1) treats `""` and `"\0"` alike, since the two share one index key (`InvalidContractStructure`, 10231). Otherwise an ordinary document could take the values of a contested one, and the contest would have nothing left to award. A contract registered earlier keeps its contest, but can no longer be updated, since an update is checked like a registration; while such a contest is live, a create outside it with the same index values is refused (`DuplicateUniqueIndexError`). A contest whose values a document took before protocol version 15 ends without a winner.
- From protocol version 15, every property of the index is a top-level property of the document: no property path such as `records.identity` and no system property such as `$ownerId` (`InvalidContractStructure`, 10231). A contested create finds the contest by reading each index value from the document's top-level properties, where such a property is never found, so no contested create could open or join the contest. A contract registered earlier keeps such an index, but can no longer be updated.
- A contested index cannot carry a [`timeRange`](time-range.md), an [`integerRange`](integer-range.md) or a ranking (a ranking needs a non-unique index), and an [index-only type](index-only.md) cannot have one.
- A document type with a contested index cannot set [`ttl`](ttl.md), nor `moderatorAbilities.delete` (see [Deletion](deletion.md)): a moderator's restore puts a document back by an ordinary insert, and a contested value is only awarded through a vote.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,27 +8,40 @@ use dpp::voting::contender_structs::FinalizedContender;
use drive::drive::votes::resolved::vote_polls::contested_document_resource_vote_poll::ContestedDocumentResourceVotePollWithContractInfo;
use drive::grovedb::TransactionArg;
mod v0;
mod v1;

impl<C> Platform<C>
where
C: CoreRPCLike,
{
/// Checks for ended vote polls
/// Awards a document to the winner of a contest, and returns whether it did. Version 0
/// always does, or returns the insert's error; from version 1 (protocol version 15) a winner whose id or unique
/// index values a document already holds is not awarded.
pub(in crate::execution) fn award_document_to_winner(
&self,
block_info: &BlockInfo,
contender: FinalizedContender,
vote_poll: &ContestedDocumentResourceVotePollWithContractInfo,
transaction: TransactionArg,
platform_version: &PlatformVersion,
) -> Result<(), Error> {
) -> Result<bool, Error> {
match platform_version
.drive_abci
.methods
.voting
.award_document_to_winner
{
0 => self.award_document_to_winner_v0(
0 => {
self.award_document_to_winner_v0(
block_info,
contender,
vote_poll,
transaction,
platform_version,
)?;
Ok(true)
}
1 => self.award_document_to_winner_v1(
block_info,
contender,
vote_poll,
Expand All @@ -37,7 +50,7 @@ where
),
version => Err(Error::Execution(ExecutionError::UnknownVersionMismatch {
method: "award_document_to_winner".to_string(),
known_versions: vec![0],
known_versions: vec![0, 1],
received: version,
})),
}
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
use crate::error::Error;
use crate::platform_types::platform::Platform;
use crate::rpc::core::CoreRPCLike;
use dpp::block::block_info::BlockInfo;
use dpp::document::DocumentV0Getters;
use dpp::platform_value::Value;
use dpp::version::PlatformVersion;
use dpp::voting::contender_structs::FinalizedContender;
use drive::drive::document::query::QueryDocumentsOutcomeV0Methods;
use drive::drive::document::shared_unique_entry::unique_index_entry_is_shared;
use drive::drive::votes::resolved::vote_polls::contested_document_resource_vote_poll::ContestedDocumentResourceVotePollWithContractInfo;
use drive::grovedb::TransactionArg;
use drive::query::{DriveDocumentQuery, InternalClauses, WhereClause, WhereOperator};
use drive::util::object_size_info::DocumentInfo;

impl<C> Platform<C>
where
C: CoreRPCLike,
{
/// Awards a document to the winner of a contest, unless the state has no room for it, and
/// returns whether it did.
///
/// Version 0 inserts the document as it is. A contender's document waits in the contest's
/// area, where the checks a document create runs do not see it, so nothing but those
/// checks, run on other creates while the contest is live, keeps its place free. When they
/// let a document take it, the insert of version 0 has no room for the winner's document
/// and returns an error. The known case is a contest its index values do not decide, which
/// registration refuses from protocol version 15 but a contract registered earlier keeps:
/// a document outside the contest holds the contest's index values from before the
/// create's state validation 3 guarded them.
///
/// This version runs the two checks of a document create on the winner's document first:
/// no document holds its id, and no document holds the values of its unique index. When
/// either fails nothing is inserted and `false` is returned, and the contest ends without
/// a winner. Otherwise version 0 inserts it.
#[inline(always)]
pub(super) fn award_document_to_winner_v1(
&self,
block_info: &BlockInfo,
contender: FinalizedContender,
vote_poll: &ContestedDocumentResourceVotePollWithContractInfo,
transaction: TransactionArg,
platform_version: &PlatformVersion,
) -> Result<bool, Error> {
let contract = vote_poll.contract.as_ref();
let document_type = vote_poll.document_type()?;

let documents_with_the_id = self.drive.query_documents(
DriveDocumentQuery {
contract,
document_type,
internal_clauses: InternalClauses {
primary_key_in_clause: None,
primary_key_equal_clause: Some(WhereClause {
field: "$id".to_string(),
operator: WhereOperator::Equal,
value: Value::Identifier(contender.document.id().to_buffer()),
}),
in_clauses: Vec::new(),
range_clause: None,
equal_clauses: Default::default(),
},
offset: None,
limit: Some(1),
order_by: Default::default(),
start_at: None,
start_at_included: false,
block_time_ms: None,
resolved_time_ranges: vec![],
sub_queries: vec![],
},
None,
false,
transaction,
Some(platform_version.protocol_version),
)?;
if !documents_with_the_id.documents().is_empty() {
return Ok(false);
}

// A type with a contested index has no other unique index
// (`ContestedUniqueIndexWithUniqueIndexError`), so the contested one is the only entry
// the insert can find taken. An entry Drive keeps under the document's id, because one
// of its keys is empty, meets no other document's, whatever values that one holds.
if unique_index_entry_is_shared(
&DocumentInfo::DocumentRefInfo((&contender.document, None)),
vote_poll.index()?,
document_type,
Some(contender.identity_id.to_buffer()),
platform_version,
)? && !self
.drive
.validate_moderated_document_uniqueness(
contract,
document_type,
&contender.document,
None,
transaction,
platform_version,
)?
.is_valid()
{
return Ok(false);
}

self.award_document_to_winner_v0(
block_info,
contender,
vote_poll,
transaction,
platform_version,
)?;
Ok(true)
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -233,15 +233,26 @@ where
ContestedDocumentVotePollWinnerInfo::Locked
} else {
let contender_id = top_contender.identity_id;
// We award the document to the winner of the vote poll
self.award_document_to_winner(
// We award the document to the winner of the vote poll.
// Changed in place for protocol version 15: the award
// tells whether it inserted the document, and a contest
// whose winner the state has no room for ends without
// one. Protocol version 14 selects award version 0, which
// always inserts or returns the insert's error, so
// nothing changes there.
if self.award_document_to_winner(
block_info,
top_contender,
&resolved_contested_document_resource_vote_poll,
transaction,
platform_version,
)?;
ContestedDocumentVotePollWinnerInfo::WonByIdentity(contender_id)
)? {
ContestedDocumentVotePollWinnerInfo::WonByIdentity(
contender_id,
)
} else {
ContestedDocumentVotePollWinnerInfo::NoWinner
}
}
} else {
ContestedDocumentVotePollWinnerInfo::NoWinner
Expand Down
Loading
Loading