PeaceFounder.Server.Controllers

struct Registrar
    metadata::Ref{Vector{UInt8}} 
    tickets::Vector{Ticket}
    signer::Signer
    hmac::HMAC
end

Represents a state for token registrar service. To initialize the service it's necessary to create a signer who can issue a valid admisssion certificates and a secret key with which a recruit client can exchange authorized messages. See also method generate(Registrar, spec).

Metadata is used as means to securelly deliver to the client most recent server specification.

Interface: hmac, hasher, key, id, tickets, in, enlist!, admit!, isadmitted

mutable struct Ticket
    const ticketid::TicketID
    timestamp::DateTime
    attempt::UInt8
    token::Digest
    tokenid::String # 
    admission::Union{Admission, Nothing}
end

Represents a ticket state for ticket with ticketid. timestamp represents time when the ticket have been issued by a registrar client in authorization system of choice, for instance, Registrars.jl; attempt is a counter with which token can be reset which is calculated with token(ticketid, attempt, hmac). Lastly admission contains a certified member pseudonym which was authetificated by the user with token.

in(ticketid::TicketID, registrar::Registrar)::Bool

Return true if there already is a ticket with ticketid.

generate(Registrar, spec::CryptoSpec)

Generate a new token registrar with unique signer and athorization key.

isadmitted(ticketid::TicketID, registrar::Registrar)

Check whether a ticket is already admitted. Returns false when either ticket is nonexistent or it's admission is nothing.

admit!(registrar::Registrar, id::Pseudonym, ticketid::TicketID)::Admission

Attempt to admit an identity pseudonym id for ticket ticketid. Authorization is expected to happen at the service layer using provided token in the invite. If a ticket is already registered return admission if it matches the provided id. Otherwise throe an error.

enlist!(registrar::Registrar, ticketid::TicketID, timestamp::DateTime; route::URI=registrar.route)::Invite

Registers a new ticket with given TicketID and returns an invite. If ticket is already registered the same invite is returned. Throws an error when ticket is already registered.

hmac(x)::HMAC

Return HMAC authorizer from a given object.

set_demespec!(registrar::Registrar, spec::Union{Digest, DemeSpec})

Replace metadata for a registrar. Note when data is replaced all unfinalized tokens need to be flushed.

tickets(registrar::Registrar)::Vector{TicketID}

Return a list of registered ticket ids.

token(ticketid::TicketID, hmac::HMAC)

Compute a recruit token for a given ticketid. Calculates it as token=Hash(Hash(0|key)|attempt|ticketid) where attempt is a counter for which token is issued.

Note: the token generation from key is made in order to support it's local computation on a remote server where QR code for registration is shown within organization website.

struct BraidChain
    members::Set{Pseudonym}
    ledger::BraidChainLedger
    spec::DemeSpec
    generator::Generator
    tree::HistoryTree
    commit::Union{Commit{ChainState}, Nothing}
end

Represents a braidchain ledger with it's associated state. Can be instantitated with a demespec file using BraidChain(::DemeSpec) method.

Interface: push!, record!, state, length, list, select, generator, commit, commit_index, ledger, leaf, root, ack_leaf, ack_root, members, commit!

push!(ledger::BraidChainController, t::Transaction)

Add an element to the BraidChainController bypassing transaction verification with the chain. This should only be used when the ledger is loaded from a trusted source like a local disk or when final root hash is validated with a trusted source.

leaf(ledger::BraidChainController, N::Int)::Digest

Return a ledger's element digest at given index.

root(ledger::BraidChainController[, N::Int])::Digest

Return a ledger root digest. In case when index is not given a current index is used.

commit(ledger::BraidChainController)

Return a current commit for a braichain.

generator(ledger[, index])

Return a generator at braidchain ledger row index. If index is omitted return the current state value.

generator(ledger::BraidChainController)

Return a current relative generator for a braidchain ledger.

isbinding(chain::BraidChainController, state::ChainState)::Bool

Check that chain state is consistent with braidchain ledger.

members(chain::BraidChainController, [n::Int])::Set

Return a set of member pseudonyms which at given anchor index can participate in voting or braiding.

select(T, predicate::Function, ledger::BraidChainController)::Union{T, Nothing}

Return a first element from a ledger with a type T which satisfies a predicate.

ack_leaf(ledger::BraidChainController, index::Int)::AckInclusion

Return a proof for record inclusion with respect to a current braidchain ledger history tree root.

ack_root(ledger::BraidChainController, index::Int)

Return a proof for the ledger root at given index with respect to the current braidchain ledger history tree root.

commit!(ledger::BraidChainController, signer::Signer)

Commit a current braidchain ledger state with a signer's issued cryptographic signature.

list(T, ledger::BraidChainController)::Vector{Tuple{Int, T}}

List braidchain elements with a given type together with their index.

reset_tree!(ledger::BraidChainController)

Recompute a chain tree hash.

mutable struct BallotBoxController
    ledger::BallotBoxLedger
    voters::Set{Pseudonym} # better than members
    collector::Pseudonym
    seed::Union{Digest, Nothing}
    queue::Vector{Vote}
    tree::HistoryTree
    commit::Union{Commit{BallotBoxState}, Nothing}
end

Represents a ballot box for a proposal. Contains proposal, a set of eligiable voters a collector who collects the votes and a seed which is selected at random when the voting starts. queue contains a list of valid votes which yet to be comitted to a ledger. A history tree is built on leafs of ledger's receipts (see a receipt method). A commit contains a collector seal on the current ballotbox state.

Interface: reset_tree!, generator, uuid, ledger, spine, index, seed, leaf, root, receipt, commit, tally, set_seed!, ack_leaf, ack_root, ack_cast, commit_index, commit_state, push!, state, validate, record!, commit!

struct PollingStation
    halls::Vector{BallotBoxController}
    crypto::CryptoSpec
end

Represents a pooling station which hosts ballotbox ledgers for every proposal collector manages.

Interface: init!, record!, commit!, commit, ack_leaf, ack_root, ack_cast, receipt, spine, ledger, tally, set_seed!

get(station::PollingStation, uuid::UUID)::BallotBoxController

Return a ballotbox ledger with a provided UUID. If none is found throws an error.

get(station::PollingStation, proposal::Digest)::BallotBoxController

Return a ballotbox which has proposal with provided digest.

getindex(ledger::BallotBoxController, index::Int)::CastRecord

Return a ledger record at provided index.

length(ledger::BallotBoxController)

Return a total length of the ledger including uncommited records in the queue.

push!(ledger::BallotBoxController, record::CastRecord)

Push a record to the ledger bypassing integrity checks. Used when loading the ledger from a trusted source such as local disk or an archive with a signed root cheksum.

leaf(ledger::BallotBoxController, N::Int)::Digest

Return a record digest used to form a history tree.

root(ledger::BallotBoxController[, N::Int])::Digest

Calculate a root for history tree at given index N. If index is not specified returns the current value.

commit(ledger::BallotBoxController)

Return a commit for the ballotbox ledger.

commit(station::PollingStation, uuid::UUID)::Commit

Return a ballotbox commit.

generator(ledger::BallotBoxController)

Return a relative generator which members use to sign votes anchored by the proposal.

index(ledger::BallotBoxController)

Return the current index of the ledger. See also length.

isbinding(vote::Vote, ack::CastAck, hasher)

Check whether acknowledgment is bound to the provided vote.

receipt(ledger::BallotBoxController, index::Int)::CastReceipt

Return a receipt for a ledger element.

receipt(station::PollingStation, uuid::UUID, N::Int)::CastReceipt

Return a receipt for a record with index N at ballotbox with uuid.

seed(ledger::BallotBoxController)::Union{Digest, Nothing}

Return a random selected seed used in the voting.

tally(station::PollingStation, uuid::UUID)

Compute a tally from ledger records a ballotbox with uuid.

uuid(ledger::BallotBoxController)

Return a UUID of the proposal.

voters(ledger::BallotBoxController)

Return a list of member pseudonyms with which members authetificate their votes.

ack_cast(ledger::BallotBoxController, index::Int)::CastAck

Compute an acknowledgment for record inclusion at index.

ack_cast(station::PollingStation, uuid::UUID, N::Int)::CastAck

Return inclusion proof with receipt and current tree commit for a leaf at index N and ballotbox with uuid.

ack_leaf(ledger::BallotBoxController, index::Int)::AckInclusion

Compute an inclusion proof ::AckInclusion for record element at given index.

ack_leaf(station::PollingStation, uuid::UUID, N::Int)::AckInclusion

Return history tree inclusion proof for a tree leaf at index N in ballotbox with uuid.

ack_root(ledger::BallotBoxController, index::Int)::AckConsistency

Compute a history tree consistency proof at index.

ack_root(station::PollingStation, uuid::UUID, N::Int)::AckConsistency

Return history tree consitency proof tree root at index N in ballotbox with uuid.

commit!(ledger::BallotBoxController[, timestamp::DataTime], signer::Signer; with_tally=nothing)

Flushes ballotbox ledger's queue and creates a commit for a current ballotbox ledger state with provided timestamp and signer. A keyword argument with_tally has three values true|false to include or exclude a tally from a commited state and nothing which uses a previous commit preference.

commit!(station::PollingStation, uuid::UUID, collector::Signer; with_tally = nothing)

Select a ballotbox with provided uuid and commit it's state with collector.

commit_index(ledger::BallotBoxController)::Union{Index, Nothing}

Index at which commit is issued. See also length and index

commit_state(ledger::BallotBoxController)

Return a committed state for a ballotbox ledger.

init!(station::PollingStation, proposal::Proposal, voters::Set{Pseudonym}[, collector::Pseudonym])

Creates a new ballotbox for given proposal with provided member pseudonyms at a relative generator anchored in the proposal. A collector is optional and provided only when it differs from one specified in the proposal.

ledger(ballotbox::BallotBoxController)::Vector{CastRecord}

Return all records from a ballotbox ledger.

ledger(station::PollingStation, uuid::UUID)::Vector{CastRecord}

Return a vector of records from a ballotbox with uuid.

record!(ledger::BallotBoxController, record::CastRecord)

Check the vote in the record for validity and include that in the ledger directly bypassing queue. This method is useful for replaying and debugging ballotbox ledger state changes. See also record!

record!(ledger::BallotBoxController, vote::Vote)

Check the vote for validity and pushes it to the queue. Returns an index N at which the vote will be recorded in the ledger. See also push!

record!(station::PollingStation, uuid::UUID, vote::Vote)::Int

Records a vote in a ballotbox with provided proposal UUID. Throws an error if a ballotbox can't be found.

record!(station::PollingStation, uuid::UUID, vote::Vote)::Int

Record a vote in a ballotbox found by proposal diggest stored in the vote. Throws an error if a ballotbox can't be found.

reset_tree!(ledger::BallotBoxController)

Recompute history tree root and cache from the elements in the ledger. This is a useful for loading the ledger all at once.

set_seed!(ledger::BallotBoxController, seed::Digest)

Set's a seed of the ballotbox.

set_seed!(station::PollingStation, uuid::UUID, seed::Digest)

Sets a seed for a ballotbox with provided uuid.

spine(ledger::BallotBoxController)::Vector{Digest}

Return a history tree leaf vector.

spine(station::PollingStation, uuid::UUID)::Vector{Digest}

Return a leaf vector for a ballotbox with proposal uuid.

validate(ledger::BallotBoxController, vote::Vote)

Check that vote can be included in the ballotbox. Is well formed, signed by a member pseudonym and cryptographic signature is valid. Raises error if either of checks fail.