@midnight/ledger v3.0.2 • Readme | API
@midnight/ledger v3.0.2 / 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
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
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
applyoffers Alice cares about). - Skip (with this method) sections Alice does not care about, obtaining
the collapsed update covering the gap from Bob.
Note that
firstFreeis not included in the tree itself, and both ends of updates are included.
- Insert (with
Parameters
• update: MerkleTreeCollapsedUpdate
Returns
applyFailed()
applyFailed(offer): LocalState
Locally marks an offer as failed, allowing inputs used in it to be spendable once more.
Parameters
• offer: Offer
Returns
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
applyProofErased()
applyProofErased(offer): LocalState
Locally applies a proof-erased offer to the current state, returning the updated state
Parameters
• offer: ProofErasedOffer
Returns
applyProofErasedTx()
applyProofErasedTx(tx, res): LocalState
Locally applies a proof-erased transaction to the current state, returning the updated state
Parameters
• tx: ProofErasedTransaction
• res: "success" | "partialSuccess" | "failure"
The result type of applying this transaction against the ledger state
Returns
applySystemTx()
applySystemTx(tx): LocalState
Locally applies a system transaction to the current state, returning the updated state
Parameters
• tx: SystemTransaction
Returns
applyTx()
applyTx(tx, res): LocalState
Locally applies a transaction to the current state, returning the updated state
Parameters
• tx: Transaction
• res: "success" | "partialSuccess" | "failure"
The result type of applying this transaction against the ledger state
Returns
serialize()
serialize(netid): Uint8Array
Parameters
• netid: NetworkId
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
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
yesIKnowTheSecurityImplicationsOfThis_encryptionSecretKey()
yesIKnowTheSecurityImplicationsOfThis_encryptionSecretKey(): EncryptionSecretKey
Returns
deserialize()
static deserialize(raw, netid): LocalState
Parameters
• raw: Uint8Array
• netid: NetworkId
Returns
fromSeed()
static fromSeed(seed): LocalState
Creates a new state from a predefined random seed (which can act as a recovery phrase)
Parameters
• seed: Uint8Array