feat: readState - state parameter added (#507)

Author: 8bcb

src/contract/Contract.ts

@@ -106,15 +106,15 @@ export interface Contract<State = unknown> {
    * Returns state of the contract at required sortKey or blockHeight.
    *
    * @param sortKeyOrBlockHeight - either a sortKey or block height at which the contract should be read
-   *
-   * @param currentTx - a set of currently evaluating interactions, that should
-   * be skipped during contract inner calls - to prevent the infinite call loop issue
-   * (mostly related to contract that use the Foreign Call Protocol)
+   * @param interactions - optional interactions to be applied on state
+   * @param signal - allows to communicate with a DOM request (such as Fetch) and abort it
+   * @param state - uses specified state to read contract state (overrides reading state from the cache)
    */
   readState(
     sortKeyOrBlockHeight?: string | number,
     interactions?: GQLNodeInterface[],
-    signal?: AbortSignal
+    signal?: AbortSignal,
+    state?: SortKeyCacheResult<EvalStateResult<State>>
   ): Promise<SortKeyCacheResult<EvalStateResult<State>>>;
 
   /**
@@ -128,10 +128,18 @@ export interface Contract<State = unknown> {
     signal?: AbortSignal
   ): Promise<SortKeyCacheResult<EvalStateResult<State>>>;
 
+  /**
+   * Reads state at a specified sortKey and applies indicated interactions
+   * @param sortKey - sortKey at which the contract should be read
+   * @param interactions - optional interactions to be applied on state
+   * @param signal - allows to communicate with a DOM request (such as Fetch) and abort it
+   * @param state -  uses specified state to read contract state (overrides reading state from the cache)
+   */
   readStateFor(
     sortKey: string,
     interactions: GQLNodeInterface[],
-    signal?: AbortSignal
+    signal?: AbortSignal,
+    state?: SortKeyCacheResult<EvalStateResult<State>>
   ): Promise<SortKeyCacheResult<EvalStateResult<State>>>;
 
   /**

src/contract/HandlerBasedContract.ts

@@ -149,7 +149,8 @@ export class HandlerBasedContract<State> implements Contract<State> {
   async readState(
     sortKeyOrBlockHeight?: string | number,
     interactions?: GQLNodeInterface[],
-    signal?: AbortSignal
+    signal?: AbortSignal,
+    state?: SortKeyCacheResult<EvalStateResult<State>>
   ): Promise<SortKeyCacheResult<EvalStateResult<State>>> {
     this.logger.info('Read state for', {
       contractTxId: this._contractTxId,
@@ -181,7 +182,8 @@ export class HandlerBasedContract<State> implements Contract<State> {
         sortKey,
         false,
         interactions,
-        signal
+        signal,
+        state
       );
       this.logger.info('Execution Context', {
         srcTxId: executionContext.contractDefinition?.srcTxId,
@@ -221,9 +223,10 @@ export class HandlerBasedContract<State> implements Contract<State> {
   async readStateFor(
     sortKey: string,
     interactions: GQLNodeInterface[],
-    signal?: AbortSignal
+    signal?: AbortSignal,
+    state?: SortKeyCacheResult<EvalStateResult<State>>
   ): Promise<SortKeyCacheResult<EvalStateResult<State>>> {
-    return this.readState(sortKey, interactions, signal);
+    return this.readState(sortKey, interactions, signal, state);
   }
 
   async readStateBatch(
@@ -635,7 +638,8 @@ export class HandlerBasedContract<State> implements Contract<State> {
     upToSortKey?: string,
     forceDefinitionLoad = false,
     interactions?: GQLNodeInterface[],
-    signal?: AbortSignal
+    signal?: AbortSignal,
+    state?: SortKeyCacheResult<EvalStateResult<State>>
   ): Promise<ExecutionContext<State, HandlerApi<State>>> {
     const { definitionLoader, interactionsLoader, stateEvaluator } = this.warp;
     let cachedState: SortKeyCacheResult<EvalStateResult<State>>;
@@ -646,7 +650,7 @@ export class HandlerBasedContract<State> implements Contract<State> {
         EvalStateResult<State>
       >;
     }
-    cachedState = cachedState || (await stateEvaluator.latestAvailableState<State>(contractTxId, upToSortKey));
+    cachedState = state || cachedState || (await stateEvaluator.latestAvailableState<State>(contractTxId, upToSortKey));
     if (upToSortKey && this.evaluationOptions().strictSortKey && cachedState?.sortKey != upToSortKey) {
       throw new Error(`State not cached at the exact required ${upToSortKey} sortKey`);
     }