Commit{T}
    state::T
    seal::Seal
end

Represents a commited ledger state to which issuer can be held accountable for integrity. It is assumed that T implements index and root necessaary to fix a ledger state.

Interface: id, issuer, verify, index, root, state

struct CryptoSpec
    hasher::HashSpec
    group::GroupSpec
    generator::Generator
end

Specification of cryptographic parameters which are used for public key cryptography, message hashing and authetification codes.

struct Digest
    data::Vector{UInt8}
end

A message digest obtained applying a hash function on a message or a document. See method digest.

struct Generator
    data::Vector{UInt8}
end

Datatype which stores cryptogrpahic group point in standart octet form intended to be used as a base. See also Pseudonym.

struct HMAC
    key::Vector{UInt8}
    hasher::HashSpec
end

Represent a hash message authetification code authorizer.

Interface: hasher, digest, key

struct Pseudonym
    pk::Vector{UInt8}
end

A datatype which stores public key in canonical standart octet form.

struct Seal
    pbkey::Pseudonym
    sig::Signature
end

A wrapper type for a signature which adds a public key of signature issuer. See seal method.

Interface: pseudonym, verify

struct Signer
    spec::CryptoSpec
    pbkey::Pseudonym
    key::BigInt
end

A signer type. See a method generate(Signer, spec) for initialization.

Interface: pseudonym, id, sign, seal, approve

root(x)::Digest

Return a ledger root hash.

digest(message::Vector{UInt8}, hasher::HashSpec)::Digest
digest(document, spec) = digest(canonicalize(message)::Vector{UInt8}, hasher(spec)::HashSpec)

Return a resulting digest applying hasher on the given message. When message is not octet string a canonicalize method is applied first.

digest(bytes::Vector{UInt8}, hasher::HashSpec)::Digest
digest(x, spec) = digest(canonicalize(x)::Vector{UInt8}, hasher(spec)::HashSpec)

Compute a hash digest. When input is not in bytes the canonicalize method is applied first.

generate(Signer, spec::CryptoSpec)::Signer

Generate a unique private key and return a Signer object.

generator(crypto::CryptoSpec)::Generator

Return a generator of the specification.

generator(spec::Spec)::Generator

Return a generator of spec.

hasher(spec)::HashSpec

Access a hasher function from a given specification.

index(x)::Int

Return an index of a ledger state.

issuer(x)

In case an object x is cryptographically signed return an issuer of who have issued the signature. See also id.

key(x)

Access a secret key of an object x.

seal(message::Vector{UInt8}[, generator::Generator], signer::Signer)::Seal

Sign a bytestring message with signer's private key and specification and return a signature as a Seal. When generator is provided it is used as a base for the signature. See also sign.

sign(digest::Digest[, generator::Generator], signer::Signer)::Signature

Sign a digest as an integer with signer's private key and specification. This method avoids running hashing twice when that is done externally. When generator is provided it is used as a base for the signature.

sign(message::Vector{UInt8}[, generator::Generator], signer::Signer)::Signature

Sign a bytestring message with signer's private key and specification. When generator is provided it is used as a base for the signature.

state(commit::Commit{T})::T

Return a ledger state. T implements index and root.

ToDo: a well specified encoding is essential here. Binary tree encoding may suffice here. More fancy approach would be to use a DER encoding. Meanwhile JSON shall be used.

pseudonym(signer::Signer, [generator])::Pseudonym

Return a pseudonym of a signer at a given relative generator. If generator is not passed returns identity pseudonym. (See also id)

pseudonym(seal::Seal)::Pseudonym

Return a pseudonym of a seal. Note that it is not equal to identity when the signature is issued on a relative generator.

pseudonym(vote::Vote)::Pseudonym

Return a pseudonym used to seal the vote.

id(document)::Pseudonym

Return identity pseudonym of a document issuer.

id(signer)::Pseudonym

Return identity pseudonym of a signer.

verify(message, seal::Seal, [generator::Generator], crypto::CryptoSpec)::Bool
verify(message, pk::Pseudonym, sig::Signature, [generator::Generator], crypto::CryptoSpec)::Bool

Verify the cryptographic signature of the message returning true if valid. An optional generator can be given when signature is issued on a relative generator differing from a base specification crypto.

verify(document[, generator::Generator], crypto::CryptoSpec)::Bool

Verify a cryptographic signature of the document returning true if valid.

verify(braidwork::BraidReceipt, crypto::CryptoSpec)::Bool

Verify a braider issued cryptographic signature for the braidwork and a zero knowledge proofs. Returns true if both checks succeed.

struct Admission
    ticketid::TicketID
    id::Pseudonym
    timestamp::DateTime
    approval::Union{Seal, Nothing}
end

Represents an admission certificate for a pseudonym id.

Interface: approve, issuer, id, ticket, [isadmitted]

struct ChainState
    index::Int
    root::Digest
    generator::Generator
    member_count::Int
    termination_bitmask::BitMask
end

Represents a chain state metadata which is sufficient for integrity checks.

Interface: index, root, generator

struct DemeSpec <: Transaction
    uuid::UUID
    title::String
    crypto::CryptoSpec
    guardian::Pseudonym
    recorder::Pseudonym
    registrar::Pseudonym
    braider::Pseudonym
    proposer::Pseudonym 
    collector::Pseudonym
    timestamp::Union{DateTime, Nothing} = nothing
    signature::Union{Signature, Nothing} = nothing
end

Represents a deme configuration parameters issued by the guardian.

• uuid::UUID an unique random generated community identifier;
• title::String a community name with which deme is represented;
• crypto::CryptoSpec cryptographic parameters for the deme;
• guardian::Pseudonym an issuer for this demespec file. Has authorithy to set a roster:
  • recorder::Pseudonym an authorithy which has rights to add new transactions and is responsable for braidchain's ledger integrity. Issues Commit{ChainState};
  • registrar::Pseudonym an authorithy which has rights to authorize new admissions to the deme. See Admission and Membership;
  • braider::Pseudonym an authorithy which can do a legitimate braid jobs for other demes. See BraidReceipt;
  • proposer::Pseudonym an authorithy which has rights to issue a proposals for the braidchain. See Proposal;
  • collector::Pseudonym an authorithy which is repsonsable for collecting votes for proposals. This is also recorded in the proposal itself.
• timestamp::Union{DateTime, Nothing} time when signature is being issued;
• signature::Union{Signature, Nothing} a guardian issued signature.

struct Membership <: Transaction
    admission::Admission
    generator::Generator
    pseudonym::Pseudonym
    approval::Union{Signature, Nothing} 
end

A new member certificate which rolls in (anouances) it's pseudonym at current generator signed with identity pseudonym certified with admission certificate issued by registrar. This two step process is necessary as a checkpoint in situations when braidchain ledger get's locked during a new member resgistration procedure.

struct TicketID
    id::Vector{UInt8}
end

Represents a unique identifier for which a recruit tooken is issued. In case of necessity id can contain a full document, for instance, registration form, proof of identity and etc. In case a privacy is an issue the id can contain a unique identifier which can be matched to an identity in an external database.

Transaction

Represents an abstract record type which can be stored in the braidchain ledger.

approve(x::T, signer::Signer)::T

Cryptographically sign a document x::T and returns a signed document with the same type. To check whether a document is signed see issuer method.

generator(member::Membership)::Generator

Generator at which member tries to roll in the braidchain.

id(member::Membership)::Pseudonym

Identity pseudonym for a member.

isbinding(admission::Admission, spec::DemeSpec)

Check whether issuer of admission is a registrar set in spec.

issuer(member::Membership)::Pseudonym

The identiy of registrar who signed admission.

members(ledger::BraidChainLedger[, index::Int])::Set{Pseudonym}

Return a set of member pseudonyms at relative generator at braidchain ledger row index. If index is omitted return a current state value.

pseudonym(member::Membership)::Pseudonym

Pseudonym for a member at the generator(member).

ticket(x::Admission)

Return a TicketID which is admitted.

ticket(member::Membership)

Ticket for a member admission certificate.

struct BraidReceipt <: Transaction
    braid::Simulator
    reset::Bool
    producer::DemeSpec
    approval::Union{Seal, Nothing}
end

Represents a braider's computation which is supported with zero knowledge proof of shuffle and decryption assuring it's corectness stored in a braid field; producer denotes a deme where the braid is made. To assert latter the the braider signs the braidwork and stores that in the aproval field. See a braid method.

Interface: approve, verify, input_generator, input_members, output_generator, output_members

approve(braid::BraidReceipt, spec::DemeSpec, braider::Signer)

Sign a braidwork with a braider. Throws an error if braider is not in the producer demespec.

braid(generator::Generator, members::Union{Vector{Pseudonym}, Set{Pseudonym}}, consumer::DemeSpec, producer::DemeSpec; verifier = (g) -> ProtocolSpec(; g))

Selects a private exponent x at random and computes a new generator $g' = g^x$ and $member_i'=member_i^x$ returns the latter in a sorted order and provides a zero knowledge proof that all operations have been performed honestly. In partucular, not including/droping new member pseudonyms in the process. consumer attributes are necessary to interepret generator and pseudonym group elements with which the computation is performed.

By default a Verificatum compatable verifier is used for performing reencryption proof of shuffle

A verifier can be configured with a keyword argument. By default a Verificatum compatable verifier for a proof of shuffle is used.

input_generator(braid::BraidReceipt)

Return input generator of the braid.

input_members(braid::BraidReceipt)

Return input member pseudonyms of the braid at provided input generator. See input_generator

output_generator(braid::BraidReceipt)

Return output genertor of the braid.

output_members(braid::BraidReceipt)

Return output member pseudonyms of the braid at a resulting output generator. See output_generator

verify(braid::BraidReceipt, crypto::CryptoSpec)

Verifies a braid approval and then it's zero knowledge proofs. A crypto argument is provided to avoid downgrading attacks.

struct Ballot
    options::Vector{String}
end

Represents a simple ballot form for multiple choice question.

struct BallotBoxState
    proposal::Digest
    seed::Digest
    index::Int
    root::Digest
    tally::Union{Nothing, Tally} 
    view::Union{Nothing, BitVector} # 
end

Represents a public ballot box state. Contains an immutable proposal and seed digest; a current ledger index, history tree root. When ellections end a tally is included in the state and a view is added listing all counted votes. Note that the view attribute is important for a client to know whether it's key have leaked and somone lese havbe superseeded it's vote by revoting.

struct CastReceipt
    vote::Digest
    timestamp::DateTime
end

Represents a ballotbox ledger receipt which is hashed for a history tree. It's sole purpose is to assure voters that their vote is included in the ledger while also adding additional metadata as timestamp and. In contrast to CastRecord it does not reveal how voter have voted thus can be published during ellections without violating fairness property. For some situations it may be useful to extend the time until the votes are published as that can disincentivice coercers and bribers as they would not know whether their coerced vote have been superseeded in revoting. See receipt method for it's construction from a CastRecord.

Note that a blind signature could be commited as H(signature|H(vote)) to avoid tagging the use of pseudonym during ellections while collector could issue only a one blind signature for a voter. Note that members whoose private key could have been stolen could not obtain a valid signature for participation and that could be a good thing!

struct CastRecord
    vote::Vote
    timestamp::DateTime
end

Represents a ballotbox ledger record. Adds a timestamp when the vote have been recorded. In future, the record will also contain a blind signature with which members could prove to everyone that they had cast their vote without revealing the link to the vote.

struct Proposal <: Transaction 
    uuid::UUID
    summary::String
    description::String
    ballot::Ballot
    open::DateTime
    closed::DateTime
    collector::Union{Pseudonym, Nothing} # 
    anchor::Union{ChainState, Nothing}
    approval::Union{Seal, Nothing} 
end

Represents a proposal for a ballot specyfing voting window, unique identifier, summary, description. Set's the collector identity which collects votes and issues vote inclusion receipts and is responsable for maintaining the ledger's integrity. The proposal also includes an anchor which sets a relative generator with which members vote anonymously. To be considered valid is signed by proposer authorizing vote to take place.

struct Selection
    option::Int
end

Represents voter's selection for a Ballot form.

struct Tally
    data::Vector{Int}
end

Represent a tally for Ballot form obtained aftert counting multiple voter's Selection forms.

struct Vote
    proposal::Digest
    seed::Digest
    selection::Selection
    seq::Int
    approval::Union{Seal, Nothing} 
end

Represents a vote for a proposal issued by a member. The proposal is stored as hash digest ensuring that member have voted on an untampered proposal. seed contains a randon string issued by collector at the moment when a vote starts to eliminate early voting / shortening a time at which coercers could act uppon. selection contians voter's preference;

seq is a serquence number counting a number of votes at which vote have been approved for a given proposal. It starts at 1 and is increased by one for every single signature made on the proposal. This is an important measure which allows to detect possible leakage of a member's private key. Also provides means for revoting ensuring that latest vote get's counted.

The vote is considered valid when it is sealed by a member's private key at a relative generator stored in the proposal.

root(state::BallotBoxState)

Return a history tree root for a current ballotbox ledger state.

generator(proposal::Proposal)

A relative generator for at which memebers sign votes for this proposal.

index(state::BallotBoxState)

Return an index for a current ballotbox ledger state.

isbinding(receipt::CastReceipt, vote::Vote, hasher::HashSpec)::Bool

Check that the receipt is bidning to a vote.

isbinding(vote::Vote, proposal::Proposal, crypto::HashSpec)

Check that the vote is bound to a proposal..

isconsistent(selection::Selection, ballot::Ballot)

Verifies that voter's selection is consistent with ballot form. For instance, whether selection is withing the range of ballot options.

issuer(proposal::Proposal)

Issuer of approval for the proposal.

pseudonym(vote::Vote)::Union{Pseudonym, Nothing}

Return a pseudonym with which vote is sealed.

receipt(record::CastRecord, hasher::HashSpec)::CastReceipt

Construct a CastReceipt from a CastRecord with a provided hasher function.

state(ledger::BallotBoxLedger; seed::Digest, root::Digest = root(ledger), with_tally::Union{Nothing, Bool} = nothing)::BallotBoxState

Return a state metadata for ballotbox ledger.

state(proposal::Proposal)::ChainState

A braidchain ledger state which is used to anchor a relative generator for members.

tally(ledger::BallotBox)

Compute a tally for a ballotbox ledger.

tally(ballot::Ballot, ballots::AbstractVector{Selection})::Tally

Count ballots, check that they are filled consistently and return a final tally.

uuid(proposal::Proposal)::UUID

UUID for a proposal. Issued by proposer and it's purpose is to croslink to an external system durring the proposal dreafting stage.

vote(proposal::Proposal, seed::Digest, selection::Selection, member::Signer; seq = 1)

Issue a vote on a proposal and provided collector seed for a member's selection.

struct AckConsistency{T}
    proof::ConsistencyProof
    commit::Commit{T}
end

Represents an ackknowledgment from the issuer that a root is permanetly included in the ledger. This acknowledgemnt assures that ledger up to index(ack) is included in the current ledger which has has index index(commit(ack)). This is useful in a combination with AckInclusion to privatelly update it's validity rather than asking an explicit element. Also ensures that other elements in the ledger are not being tampered with.

Interface: root, id, issuer, commit, index, verify

struct AckInclusion{T}
    proof::InclusionProof
    commit::Commit{T}
end

Represents an acknowldgment from the issuer that a leaf is permanently included in the ledger. In case the ledger is tampered with this acknowledgement acts as sufficient proof to blame the issuer.

Interface: leaf, id, issuer, commit, index, verify

struct CastAck
    receipt::CastReceipt
    ack::AckInclusion{BallotBoxState}
end

Represents a reply to a voter when a vote have been included in the ballotbox ledger. Contains a receipt and inlcusion acknowledgment. In future would also include a blind signature in the reply for a proof of participation. To receive this reply (with a blind signature in the future) a voter needs to send a vote which is concealed during ellections and thus tagging votes with blind signatures from reply to monitor revoting would be as hard as monitoring the submitted votes.

struct TicketStatus ticketid::TicketID timestamp::DateTime admission::Union{Nothing, Admission} end

Represents a public state of a ticket. See isadmitted method.

leaf(ack::AckInclusion)

Access a leaf diggest for which the acknowledgment is made.

root(x::AckConsistency)

Access a root diggest for which the acknowledgment is made.

commit(x)

Access a commit of an object x.

commit(ack::CastAck)

Return a commit from a CastAck.

index(ack::AckConsistency)

Return an index for a root at which the consistency proof is made. To obtain the current ledger index use index(commit(ack)).

index(ack::AckInclusion)::Int

Return an index at which the leaf is recorded in the ledger. To obtain the current ledger index use index(commit(ack)).

isbinding(receipt::CastReceipt, ack::AckInclusion, hasher::HashSpec)::Bool

Check that cast receipt is binding to received inclusion acknowledgment.

isbinding(record::Transaction, ack::AckInclusion{ChainState}, crypto::CryptoSpec)

A generic method checking whether transaction is included in the braidchain.

isbinding(ack::CastAck, proposal::Proposal, hasher::HashSpec)::Bool

Check that acknowledgment is legitimate meaning that it is issued by a collector listed in the proposal.

verify(ack::CastAck, crypto::CryptoSpec)::Bool

Verify the cast acknowledgment cryptographic signature.

isadmitted(status::TicketStatus)

Check whether ticket is addmitted.