0280299104
Fix broken IssuerFlowTest Fix IssuerFlowTests after rebase. Resolve conflicts after rebase. Soft locking converted to use persistent store. Added additional optional 'includeLockStates' parameter in VaultService states API call. Added Vault softLocked states query API call. Fixed commercial paper failing test. Improved exception handling on soft locking UPDATE statement. Using SELECT FOR UPDATE to ensure correct soft locking data visibility. Db query operations moved out of mutex code (as locking managed by underlying DB) Adjusted logging severity levels. Adjusted logging severity levels. GenerateSpending now performing fine grained query for unconsumed states by joining with contract_cash_states table. Using H2 proprietary cummulative counting feature (using sessioni SET variables) Refactored and simplified HibernateObserver constructor to enable usage in JUnit tests. Event generator issues larger random amounts (10,000..1,000,000) to those than are spent (0..10,000) Adjusted Issue (5:1) and Exit (10:1) generation frequency vs spending. Minor fixes: added optional lockid into select for spending criteria, set notary, additional trace logging. Generate Cash Schema by default upon node start-up (as part of NodeSchemaService initialisation). Explicitly close JDBC statements in finally() blocks. Tightened HibernateObserver constructor. Fix CommercialPaper test (was missing auto-generation of CONTRACT_CASH table) Revert default JVM size back to 200Mb. Revert default number of iterations in Explorer Node Simulation mode (back to 10000 with .5 sec sleep interval). Remove redundant setter function. Added TODO messages indicating Requery / H2 restrictions & caveats. Consumed states lock updates now performed in general consumed state Update. Updated/added Soft Locking documentation. Addressed initial PR comments: use THREAD_LOCAL_KRYO, use AbstractParty, extract helper method, improve readability, address some doc typos Addressed PR comment: removed lockId from WireTransaction. Fixed soft locking UPDATE statements. Improvements to VaultSoftLockManager for auto-registration of soft locks for flows with spendable states (as notifications from vault). Other optimisations (IssuerFlow no longer explicitly reserve/release issued state) and improvements (soft lock release management of soft locks, docs update) Performance update: now using Requery for UPDATE in release soft locking (non-composite key statement) Removed redundant TODO messages (TODO: revisit Kryo bug when using THREAD_LOCAL_KYRO) Minor fixes following rebase Fixed failing JUnit following rebase Addressed MH PR review items (1st pass) Fix broken JUnit Significant changes to RDBMS operations within coin selection and soft locking as requested by PR review. (Removed SELECT FOR UPDATE; added RETRY upon coin selection; reverting partial soft locks) Addressed a number of PR review requests added by MH (comments/spelling, lockID instantiation, HibernateObserver instantiation, cash schema white-listing usage) Addressed latest PR review comments from RP. Minor fixes following rebase from master. Fixed final failing JUnit (issuer flow concurrent). Updated TraderDemo to trigger concurrent issuance of cash. Fixed compiler warning on lockId null check. Fixed subtle bug in coin selection intermittently surfaced in IntegrationTestTutorial. Fixed small memory leak. Removed stray } in logger trace message. Slight rewording of description of Soft Locking in docs. Renamed NoStatesAvailableException to StatesNotAvailableException. generateSpend is now Suspendable (calls sleep method on flow upon coin selection retry). Added companion function to enable a Strand to sleep but without locking transactional context. Improved logging, changed to StateNotAvailableException, using Flow sleep upon retry, tweaked SELECT criteria in coin selection, fixed bug when insufficient states selectable, generateSpend is now @suspendable Improved handling and logging of flow results in Simulation Mode. Fixed minor error in sleep when not an active flow. Retry coin selection when unavailable states (as these may become available as new states). Additional debug logging to highlight and identify H2 coin selection sporadic bug. Inlined sleep method due to intermittent Quasar error. Re-introduce selection clause that prevents selection and temporary locking of already locked states (by other flows). Improved trace logging for coin selection (SQL row level info). Correctly calling FlowStateMachineImpl sleep (now inlined and working correctly) Fixed rebase error. Remove redundant TODO message.
3.8 KiB
Soft Locking
Soft Locking is implemented in the vault to try and prevent a node constructing transactions that attempt to use the same input(s) simultaneously. Such transactions would result in naturally wasted work when the notary rejects them as double spend attempts.
Soft locks are automatically applied to coin selection (eg. cash spending) to ensure that no two transactions attempt to spend the same fungible states. The outcome of such an eventuality will result in an InsufficientBalanceException for one of the requesters if there are insufficient number of fungible states available to satisfy both requests.
Note
The Cash Contract schema table is now automatically generated upon node startup as Coin Selection now uses this table to ensure correct locking and selection of states to satisfy minimum requested spending amounts.
Soft locks are also automatically applied within flows that issue or receive new states. These states are effectively soft locked until flow termination (exit or error) or by explicit release.
In addition, the VaultService exposes a number of functions a developer may use to explicitly reserve, release and query soft locks associated with states as required by their CorDapp application logic:
../../core/src/main/kotlin/net/corda/core/node/services/Services.kt
You can also control whether soft locked states are retrieved in general vault queries by setting an optional boolean includeSoftLockedStates flag (which is set to true by default)
../../core/src/main/kotlin/net/corda/core/node/services/Services.kt
Explicit Usage
Soft locks are associated with transactions, and typically within the lifecycle of a flow. Specifically, every time a flow is started a soft lock identifier is associated with that flow for its duration (and released upon it's natural termination or in the event of an exception). The VaultSoftLockManager is responsible within the Node for automatically managing this soft lock registration and release process for flows. The TransactionBuilder class has a new lockId field for the purpose of tracking lockable states. By default, it is automatically set to a random UUID (outside of a flow) or to a flow's unique ID (within a flow).
Upon building a new transaction to perform some action for a set of states on a contract, a developer must explicitly register any states they may wish to hold until that transaction is committed to the ledger. These states will be effectively 'soft locked' (not usable by any other transaction) until the developer explicitly releases these or the flow terminates or errors (at which point they are automatically released).
Use Cases
A prime example where soft locking is automatically enabled is within the process of issuance and transfer of fungible state (eg. Cash). An issuer of some fungible asset (eg. Bank of Corda) may wish to transfer that new issue immediately to the issuance requester (eg. Big Corporation). This issuance and transfer operation must be atomic such that another flow (or instance of the same flow) does not step in and unintentionally spend the states issued by Bank of Corda before they are transferred to the intended recipient. Soft locking will automatically prevent new issued states within IssuerFlow from being spendable by any other flow until such time as the IssuerFlow itself terminates.
Other use cases for soft locking may involve competing flows attempting to match trades or any other concurrent activities that may involve operating on an identical set of unconsumed states.