Skip to main content

@midnight/ledger v2.0.8 • Readme | API

@midnight/ledger v2.0.8 / LocalState

Class: LocalState

The local state of a user/wallet, consisting of their secret key, and a set of unspent coins.

It also keeps track of coins that are in-flight, either expecting to spend or expecting to receive, and a local copy of the global coin commitment Merkle tree to generate proofs against.

Constructors​

new LocalState()​

new LocalState(): LocalState

Creates a new state with a randomly sampled secret key

Returns​

LocalState

Properties​

coinPublicKey​

readonly coinPublicKey: string;

The coin public key of this wallet

coins​

readonly coins: Set<QualifiedCoinInfo>;

The set of spendable coins of this wallet

encryptionPublicKey​

readonly encryptionPublicKey: string;

The encryption public key of this wallet

firstFree​

readonly firstFree: bigint;

The first free index in the internal coin commitments Merkle tree. This may be used to identify which merkle tree updates are necessary.

pendingOutputs​

readonly pendingOutputs: Map<string, CoinInfo>;

The outputs that this wallet is expecting to receive in the future

pendingSpends​

readonly pendingSpends: Map<string, QualifiedCoinInfo>;

The spends that this wallet is expecting to be finalized on-chain in the future

Methods​

apply()​

apply(offer): LocalState

Locally applies an offer to the current state, returning the updated state

Parameters​

• offer: Offer

Returns​

LocalState

applyCollapsedUpdate()​

applyCollapsedUpdate(update): LocalState

Applies a collapsed Merkle tree update to the current local state, fast forwarding through the indices included in it, if it is a correct update.

The general flow for usage if Alice is in state A, and wants to ask Bob how to reach the new state B, is:

  • Find where she left off – what's her firstFree?
  • Find out where she's going – ask for Bob's firstFree.
  • Find what contents she does care about – ask Bob for the filtered entries she want to include proper in her tree.
  • In order, of Merkle tree indicies:
    • Insert (with apply offers Alice cares about).
    • Skip (with this method) sections Alice does not care about, obtaining the collapsed update covering the gap from Bob. Note that firstFree is not included in the tree itself, and both ends of updates are included.

Parameters​

• update: MerkleTreeCollapsedUpdate

Returns​

LocalState

applyFailed()​

applyFailed(offer): LocalState

Locally marks an offer as failed, allowing inputs used in it to be spendable once more.

Parameters​

• offer: Offer

Returns​

LocalState

applyFailedProofErased()​

applyFailedProofErased(offer): LocalState

Locally marks an proof-erased offer as failed, allowing inputs used in it to be spendable once more.

Parameters​

• offer: ProofErasedOffer

Returns​

LocalState

applyProofErased()​

applyProofErased(offer): LocalState

Locally applies a proof-erased offer to the current state, returning the updated state

Parameters​

• offer: ProofErasedOffer

Returns​

LocalState

serialize()​

serialize(): Uint8Array

Returns​

Uint8Array

spend()​

spend(coin): [LocalState, UnprovenInput]

Initiates a new spend of a specific coin, outputting the corresponding UnprovenInput, and the updated state marking this coin as in-flight.

Parameters​

• coin: QualifiedCoinInfo

Returns​

[LocalState, UnprovenInput]

spendFromOutput()​

spendFromOutput(coin, output): [LocalState, UnprovenTransient]

Initiates a new spend of a new-yet-received output, outputting the corresponding UnprovenTransient, and the updated state marking this coin as in-flight.

Parameters​

• coin: QualifiedCoinInfo

• output: UnprovenOutput

Returns​

[LocalState, UnprovenTransient]

toString()​

toString(compact?): string

Parameters​

• compact?: boolean

Returns​

string

watchFor()​

watchFor(coin): LocalState

Adds a coin to the list of coins that are expected to be received

This should be used if an output is creating a coin for this wallet, which does not contain a ciphertext to detect it. In this case, the wallet must know the commitment ahead of time to notice the receipt.

Parameters​

• coin: CoinInfo

Returns​

LocalState

yesIKnowTheSecurityImplicationsOfThis_encryptionSecretKey()​

yesIKnowTheSecurityImplicationsOfThis_encryptionSecretKey(): EncryptionSecretKey

Returns​

EncryptionSecretKey

deserialize()​

static deserialize(raw): LocalState

Parameters​

• raw: Uint8Array

Returns​

LocalState

fromSeed()​

static fromSeed(seed): LocalState

Creates a new state from a predefined random seed (which can act as a recovery phrase)

Parameters​

• seed: Uint8Array

Returns​

LocalState