account

package
v0.0.0-...-8fce49c Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 13, 2025 License: AGPL-3.0 Imports: 18 Imported by: 0

Documentation

Index

Constants

View Source 
const PartTableSchemaName = "parttable"

PartTableSchemaName is the name of the table in the Schema Versions table storing the table + version details

View Source 
const PartTableSchemaVersion = 3

PartTableSchemaVersion is the latest version of the PartTable schema

Variables

View Source 
var ErrActiveKeyNotFound = errors.New("no active participation key found for account")

ErrActiveKeyNotFound is used when attempting to update an account with no active key

View Source 
var ErrAlreadyInserted = errors.New("these participation keys are already inserted")

ErrAlreadyInserted is used when inserting a key which already exists in the registry.

View Source 
var ErrInvalidRegisterRange = errors.New("key would not be active within range")

ErrInvalidRegisterRange is used when attempting to register a participation key on a round that is out of range.

View Source 
var ErrMultipleKeysForID = errors.New("multiple valid keys found for the same participationID")

ErrMultipleKeysForID this should never happen. Multiple keys with the same participationID

View Source 
var ErrMultipleValidKeys = errors.New("multiple valid keys found while recording key usage")

ErrMultipleValidKeys is used when recording a result but multiple valid keys were found. This should not be possible.

View Source 
var ErrNoKeyForID = errors.New("no valid key found for the participationID")

ErrNoKeyForID there may be cases where a key is deleted and used at the same time, so this error should be handled.

View Source 
var ErrParticipationIDNotFound = errors.New("the participation ID was not found")

ErrParticipationIDNotFound is used when attempting to update a set of keys which do not exist.

View Source 
var ErrRequestedRoundOutOfRange = errors.New("request range is not within the validity range")

ErrRequestedRoundOutOfRange is used when the requested round for GetForRound is outside the valid range of this participation

View Source 
var ErrSecretNotFound = errors.New("the participation ID did not have secrets for the requested round")

ErrSecretNotFound is used when attempting to lookup secrets for a particular round.

View Source 
var ErrStateProofVerifierNotFound = errors.New("record contains no StateProofVerifier")

ErrStateProofVerifierNotFound states that no state proof field was found.

View Source 
var ErrUnknownParticipationAction = errors.New("unknown participation action")

ErrUnknownParticipationAction is used when record is given something other than the known actions.

View Source 
var ErrUnsupportedSchema = fmt.Errorf("unsupported participation file schema version (expected %d)", PartTableSchemaVersion)

ErrUnsupportedSchema is the error returned when the PartTable schema version is wrong.

Functions

func DefaultKeyDilution 

func DefaultKeyDilution(first, last basics.Round) uint64

DefaultKeyDilution computes the default dilution based on first and last rounds as the sqrt of validity window.

func Migrate 

func Migrate(partDB db.Accessor) error

Migrate is called when loading participation keys. Calls through to the migration helper and returns the result.

func ParticipationKeyIdentityMaxSize 

func ParticipationKeyIdentityMaxSize() (s int)

MaxSize returns a maximum valid message size for this message type

func StateProofKeysMaxSize 

func StateProofKeysMaxSize() (s int)

MaxSize returns a maximum valid message size for this message type

Types

type Participation 

type Participation struct {
	Parent basics.Address

	VRF    *crypto.VRFSecrets
	Voting *crypto.OneTimeSignatureSecrets
	// StateProofSecrets is used to sign state proofs.
	StateProofSecrets *merklesignature.Secrets

	// The first and last rounds for which this account is valid, respectively.
	//
	// When lastValid has concluded, this set of secrets is destroyed.
	FirstValid basics.Round
	LastValid  basics.Round

	KeyDilution uint64
}

A Participation encapsulates a set of secrets which allows a root to participate in consensus. All such accounts are associated with a parent root account via the Address (although this parent account may not be resident on this machine).

Participations are allowed to vote on a user's behalf for some range of rounds. After this range, all remaining secrets are destroyed.

For correctness, all Roots should have no more than one Participation globally active at any time. If this condition is violated, the Root may equivocate. (Algorand tolerates a limited fraction of misbehaving accounts.)

func (Participation) Address 

func (part Participation) Address() basics.Address

Address returns the root account under which this participation account is registered.

func (Participation) GenerateRegistrationTransaction 

func (part Participation) GenerateRegistrationTransaction(fee basics.MicroAlgos, txnFirstValid, txnLastValid basics.Round, leaseBytes [32]byte, includeStateProofKeys bool) transactions.Transaction

GenerateRegistrationTransaction returns a transaction object for registering a Participation with its parent.

func (Participation) ID 

func (part Participation) ID() ParticipationID

ID computes a ParticipationID.

func (Participation) OverlapsInterval 

func (part Participation) OverlapsInterval(first, last basics.Round) bool

OverlapsInterval returns true if the partkey is valid at all within the range of rounds (inclusive)

func (Participation) StateProofSigner 

func (part Participation) StateProofSigner() *merklesignature.Secrets

StateProofSigner returns the key used to sign on State Proofs. might return nil!

func (Participation) StateProofVerifier 

func (part Participation) StateProofVerifier() *merklesignature.Verifier

StateProofVerifier returns the verifier for the StateProof keys.

func (Participation) VRFSecrets 

func (part Participation) VRFSecrets() *crypto.VRFSecrets

VRFSecrets returns the VRF secrets associated with this Participation account.

func (Participation) ValidInterval 

func (part Participation) ValidInterval() (first, last basics.Round)

ValidInterval returns the first and last rounds for which this participation account is valid.

func (Participation) VotingSecrets 

func (part Participation) VotingSecrets() *crypto.OneTimeSignatureSecrets

VotingSecrets returns the voting secrets associated with this Participation account.

type ParticipationAction 

type ParticipationAction int

ParticipationAction is used when recording participation actions. 

const (
	Vote ParticipationAction = iota
	BlockProposal
	StateProof
)

ParticipationAction types

type ParticipationID 

type ParticipationID crypto.Digest

ParticipationID identifies a particular set of participation keys.

func ParseParticipationID 

func ParseParticipationID(str string) (d ParticipationID, err error)

ParseParticipationID takes a string and returns a ParticipationID object

func (ParticipationID) IsZero 

func (pid ParticipationID) IsZero() bool

IsZero returns true if the ParticipationID is all zero bytes.

func (ParticipationID) String 

func (pid ParticipationID) String() string

String prints a b32 version of this ID.

type ParticipationKeyIdentity 

type ParticipationKeyIdentity struct {
	Parent      basics.Address                  `codec:"addr"`
	VRFSK       crypto.VrfPrivkey               `codec:"vrfsk"`
	VoteID      crypto.OneTimeSignatureVerifier `codec:"vote-id"`
	FirstValid  basics.Round                    `codec:"fv"`
	LastValid   basics.Round                    `codec:"lv"`
	KeyDilution uint64                          `codec:"kd"`
	// contains filtered or unexported fields
}

ParticipationKeyIdentity is for msgpack encoding the participation data.

func (*ParticipationKeyIdentity) CanMarshalMsg 

func (_ *ParticipationKeyIdentity) CanMarshalMsg(z interface{}) bool

func (*ParticipationKeyIdentity) CanUnmarshalMsg 

func (_ *ParticipationKeyIdentity) CanUnmarshalMsg(z interface{}) bool

func (*ParticipationKeyIdentity) ID 

func (id *ParticipationKeyIdentity) ID() ParticipationID

ID creates a ParticipationID hash from the identity file.

func (*ParticipationKeyIdentity) MarshalMsg 

func (z *ParticipationKeyIdentity) MarshalMsg(b []byte) (o []byte)

MarshalMsg implements msgp.Marshaler

func (*ParticipationKeyIdentity) MsgIsZero 

func (z *ParticipationKeyIdentity) MsgIsZero() bool

MsgIsZero returns whether this is a zero value

func (*ParticipationKeyIdentity) Msgsize 

func (z *ParticipationKeyIdentity) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*ParticipationKeyIdentity) ToBeHashed 

func (id *ParticipationKeyIdentity) ToBeHashed() (protocol.HashID, []byte)

ToBeHashed implements the Hashable interface.

func (*ParticipationKeyIdentity) UnmarshalMsg 

func (z *ParticipationKeyIdentity) UnmarshalMsg(bts []byte) (o []byte, err error)

func (*ParticipationKeyIdentity) UnmarshalMsgWithState 

func (z *ParticipationKeyIdentity) UnmarshalMsgWithState(bts []byte, st msgp.UnmarshalState) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

type ParticipationRecord 

type ParticipationRecord struct {
	ParticipationID ParticipationID

	Account     basics.Address
	FirstValid  basics.Round
	LastValid   basics.Round
	KeyDilution uint64

	LastVote          basics.Round
	LastBlockProposal basics.Round
	LastStateProof    basics.Round
	EffectiveFirst    basics.Round
	EffectiveLast     basics.Round

	StateProof *merklesignature.Verifier
	VRF        *crypto.VRFSecrets
	Voting     *crypto.OneTimeSignatureSecrets
}

ParticipationRecord contains all metadata relating to a set of participation keys.

func (ParticipationRecord) Duplicate 

func (r ParticipationRecord) Duplicate() ParticipationRecord

Duplicate creates a copy of the current object. This is required once secrets are stored.

func (ParticipationRecord) IsZero 

func (r ParticipationRecord) IsZero() bool

IsZero returns true if the object contains zero values.

func (ParticipationRecord) OverlapsInterval 

func (r ParticipationRecord) OverlapsInterval(first, last basics.Round) bool

OverlapsInterval returns true if the partkey is valid at all within the range of rounds (inclusive)

type ParticipationRecordForRound 

type ParticipationRecordForRound struct {
	ParticipationRecord
}

ParticipationRecordForRound contains participant's secrets that corresponds to one specific round. In Addition, it also returns the participation metadata

func (ParticipationRecordForRound) IsZero 

func (r ParticipationRecordForRound) IsZero() bool

IsZero returns true if the object contains zero values.

func (*ParticipationRecordForRound) VotingSigner 

func (r *ParticipationRecordForRound) VotingSigner() crypto.OneTimeSigner

VotingSigner returns the voting secrets associated with this Participation account, together with the KeyDilution value.

type ParticipationRegistry 

type ParticipationRegistry interface {
	// Insert adds a record to storage and computes the ParticipationID
	Insert(record Participation) (ParticipationID, error)

	// AppendKeys appends state proof keys to an existing Participation record. Keys can only be appended
	// once, an error will occur when the data is flushed when inserting a duplicate key.
	AppendKeys(id ParticipationID, keys StateProofKeys) error

	// DeleteStateProofKeys removes all stateproof keys up to, and not including, a given round
	DeleteStateProofKeys(id ParticipationID, round basics.Round) error

	// Delete removes a record from storage.
	Delete(id ParticipationID) error

	// DeleteExpired removes all records and ephemeral voting keys from storage that are expired on the given round.
	DeleteExpired(latestRound basics.Round, proto config.ConsensusParams) error

	// Get a participation record.
	Get(id ParticipationID) ParticipationRecord

	// GetAll of the participation records.
	GetAll() []ParticipationRecord

	// GetForRound fetches a record with voting secrets for a particular round.
	GetForRound(id ParticipationID, round basics.Round) (ParticipationRecordForRound, error)

	// GetStateProofSecretsForRound fetches a record with stateproof secrets for a particular round.
	GetStateProofSecretsForRound(id ParticipationID, round basics.Round) (StateProofSecretsForRound, error)

	// HasLiveKeys quickly tests to see if there is a valid participation key over some range of rounds
	HasLiveKeys(from, to basics.Round) bool

	// Register updates the EffectiveFirst and EffectiveLast fields. If there are multiple records for the account
	// then it is possible for multiple records to be updated.
	Register(id ParticipationID, on basics.Round) error

	// Record sets the Last* field for the active ParticipationID for the given account.
	Record(account basics.Address, round basics.Round, participationType ParticipationAction) error

	// Flush ensures that all changes have been written to the underlying data store.
	Flush(timeout time.Duration) error

	// Close any resources used to implement the interface.
	Close()
}

ParticipationRegistry contain all functions for interacting with the Participation Registry.

func MakeParticipationRegistry 

func MakeParticipationRegistry(accessor db.Pair, log logging.Logger) (ParticipationRegistry, error)

MakeParticipationRegistry creates a db.Accessor backed ParticipationRegistry.

type PersistedParticipation 

type PersistedParticipation struct {
	Participation

	Store db.Accessor
}

PersistedParticipation encapsulates the static state of the participation for a single address at any given moment, while providing the ability to handle persistence and deletion of secrets.

func FillDBWithParticipationKeys 

func FillDBWithParticipationKeys(store db.Accessor, address basics.Address, firstValid, lastValid basics.Round, keyDilution uint64) (part PersistedParticipation, err error)

FillDBWithParticipationKeys initializes the passed database with participation keys

func RestoreParticipation 

func RestoreParticipation(store db.Accessor) (acc PersistedParticipation, err error)

RestoreParticipation restores a Participation from a database handle.

func RestoreParticipationWithSecrets 

func RestoreParticipationWithSecrets(store db.Accessor) (PersistedParticipation, error)

RestoreParticipationWithSecrets restores a Participation from a database handle. In addition, this function also restores all stateproof secrets

func (PersistedParticipation) Close 

func (part PersistedParticipation) Close()

Close closes the underlying database handle.

func (PersistedParticipation) DeleteOldKeys 

func (part PersistedParticipation) DeleteOldKeys(current basics.Round, proto config.ConsensusParams) <-chan error

DeleteOldKeys securely deletes ephemeral keys for rounds strictly older than the given round.

func (PersistedParticipation) Persist 

func (part PersistedParticipation) Persist() error

Persist writes a Participation out to a database on the disk

func (PersistedParticipation) PersistNewParent 

func (part PersistedParticipation) PersistNewParent() error

PersistNewParent writes a new parent address to the partkey database.

func (PersistedParticipation) PersistWithSecrets 

func (part PersistedParticipation) PersistWithSecrets() error

PersistWithSecrets writes Participation struct to the database along with all the secrets it contains

type Root 

type Root struct {
	// contains filtered or unexported fields
}

A Root encapsulates a set of secrets which controls some store of money.

A Root is authorized to spend money and create Participations for which this account is the parent.

It handles persistence and secure deletion of secrets.

func GenerateRoot 

func GenerateRoot(store db.Accessor) (Root, error)

GenerateRoot uses the system's source of randomness to generate an account.

func ImportRoot 

func ImportRoot(store db.Accessor, seed [32]byte) (acc Root, err error)

ImportRoot uses a provided source of randomness to instantiate an account.

func RestoreRoot 

func RestoreRoot(store db.Accessor) (acc Root, err error)

RestoreRoot restores a Root from a database handle.

func (Root) Address 

func (root Root) Address() basics.Address

Address returns the address associated with the Root account.

func (Root) Secrets 

func (root Root) Secrets() *crypto.SignatureSecrets

Secrets returns the signing secrets associated with the Root account.

type SortUint64 

type SortUint64 = basics.SortUint64

SortUint64 implements sorting by uint64 keys for canonical encoding of maps in msgpack format.

type StateProofKeys 

type StateProofKeys []merklesignature.KeyRoundPair

StateProofKeys represents a set of ephemeral stateproof keys with their corresponding round

func (StateProofKeys) CanMarshalMsg 

func (_ StateProofKeys) CanMarshalMsg(z interface{}) bool

func (*StateProofKeys) CanUnmarshalMsg 

func (_ *StateProofKeys) CanUnmarshalMsg(z interface{}) bool

func (StateProofKeys) MarshalMsg 

func (z StateProofKeys) MarshalMsg(b []byte) (o []byte)

MarshalMsg implements msgp.Marshaler

func (StateProofKeys) MsgIsZero 

func (z StateProofKeys) MsgIsZero() bool

MsgIsZero returns whether this is a zero value

func (StateProofKeys) Msgsize 

func (z StateProofKeys) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*StateProofKeys) UnmarshalMsg 

func (z *StateProofKeys) UnmarshalMsg(bts []byte) (o []byte, err error)

func (*StateProofKeys) UnmarshalMsgWithState 

func (z *StateProofKeys) UnmarshalMsgWithState(bts []byte, st msgp.UnmarshalState) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

type StateProofSecretsForRound 

type StateProofSecretsForRound struct {
	ParticipationRecord

	StateProofSecrets *merklesignature.Signer
}

StateProofSecretsForRound contains participant's state proof secrets that corresponds to one specific round. In Addition, it also returns the participation metadata. If there are no secrets for the round a nil is returned in Stateproof field.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.