@xyo-network/diviner-stateful 2.84.1

package/dist/node/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/Schema.ts","../../src/Config.ts","../../src/Diviner.ts","../../src/DivinerMixin.ts"],"sourcesContent":["export const StatefulDivinerSchema = 'network.xyo.diviner.stateful' as const\nexport type StatefulDivinerSchema = typeof StatefulDivinerSchema\n","import { DivinerConfig } from '@xyo-network/diviner-model'\n\nimport { StatefulDivinerSchema } from './Schema'\n\n/**\n * The schema for a Stateful Diviner config\n */\nexport const StatefulDivinerConfigSchema = `${StatefulDivinerSchema}.config` as const\n/**\n * The schema for a Stateful Diviner config\n */\nexport type StatefulDivinerConfigSchema = typeof StatefulDivinerConfigSchema\n\n/**\n * The config for a Stateful Diviner\n */\nexport type StatefulDivinerConfig = DivinerConfig<{\n  schema: StatefulDivinerConfigSchema\n  stateStore: {\n    archivist: string\n    boundWitnessDiviner: string\n    payloadDiviner: string\n  }\n}>\n","import { assertEx } from '@xylabs/assert'\nimport { AbstractDiviner } from '@xyo-network/abstract-diviner'\nimport { ArchivistWrapper } from '@xyo-network/archivist-wrapper'\nimport { BoundWitnessBuilder } from '@xyo-network/boundwitness-builder'\nimport { isBoundWitness } from '@xyo-network/boundwitness-model'\nimport { BoundWitnessDivinerQueryPayload, BoundWitnessDivinerQuerySchema } from '@xyo-network/diviner-boundwitness-model'\nimport { DivinerConfigSchema, DivinerModule, DivinerModuleEventData } from '@xyo-network/diviner-model'\nimport { DivinerWrapper } from '@xyo-network/diviner-wrapper'\nimport { isModuleState, ModuleState, ModuleStateSchema, StateDictionary } from '@xyo-network/module-model'\nimport { PayloadBuilder } from '@xyo-network/payload-builder'\nimport { Payload } from '@xyo-network/payload-model'\n\nimport { StatefulDivinerConfigSchema } from './Config'\nimport { StatefulDivinerParams } from './Params'\n\nconst moduleName = 'StatefulDiviner'\n\n/**\n * A Diviner that maintains state\n */\nexport abstract class StatefulDiviner<\n  TParams extends StatefulDivinerParams = StatefulDivinerParams,\n  TIn extends Payload = Payload,\n  TOut extends Payload = Payload,\n  TEventData extends DivinerModuleEventData<DivinerModule<TParams>, TIn, TOut> = DivinerModuleEventData<DivinerModule<TParams>, TIn, TOut>,\n  TState extends StateDictionary = StateDictionary,\n> extends AbstractDiviner<TParams, TIn, TOut, TEventData> {\n  static override readonly configSchemas: string[] = [DivinerConfigSchema, StatefulDivinerConfigSchema]\n\n  /**\n   * The last state\n   */\n  protected _lastState?: ModuleState<TState>\n\n  /**\n   * Commit the internal state of the Diviner process. This is similar\n   * to a transaction completion in a database and should only be called\n   * when results have been successfully persisted to the appropriate\n   * external stores.\n   * @param nextState The state to commit\n   */\n  protected async commitState(nextState: ModuleState<TState>) {\n    // Don't commit state if no state has changed\n    if (nextState.state.offset === this._lastState?.state.offset) return\n    this._lastState = nextState\n    const archivist = await this.getArchivistForStateStore()\n    const [bw] = await new BoundWitnessBuilder().payload(nextState).witness(this.account).build()\n    await archivist.insert([bw, nextState])\n  }\n\n  /**\n   * Retrieves the archivist for the specified store\n   * @param store The store to retrieve the archivist for\n   * @returns The archivist for the specified store\n   */\n  protected async getArchivistForStateStore() {\n    const name = assertEx(this.config?.stateStore.archivist, () => `${moduleName}: Config for stateStore.archivist not specified`)\n    const mod = assertEx(await this.resolve(name), () => `${moduleName}: Failed to resolve stateStore.archivist`)\n    return ArchivistWrapper.wrap(mod, this.account)\n  }\n\n  /**\n   * Retrieves the BoundWitness Diviner for the specified store\n   * @param store The store to retrieve the BoundWitness Diviner for\n   * @returns The BoundWitness Diviner for the specified store\n   */\n  protected async getBoundWitnessDivinerForStateStore() {\n    const name = assertEx(this.config?.stateStore.boundWitnessDiviner, () => `${moduleName}: Config for stateStore.boundWitnessDiviner not specified`)\n    const mod = assertEx(await this.resolve(name), () => `${moduleName}: Failed to resolve stateStore.boundWitnessDiviner`)\n    return DivinerWrapper.wrap(mod, this.account)\n  }\n\n  /**\n   * Retrieves the Payload Diviner for the specified store\n   * @param store The store to retrieve the Payload Diviner for\n   * @returns The Payload Diviner for the specified store\n   */\n  protected async getPayloadDivinerForStateStore() {\n    const name = assertEx(this.config?.stateStore?.payloadDiviner, () => `${moduleName}: Config for stateStore.payloadDiviner not specified`)\n    const mod = assertEx(await this.resolve(name), () => `${moduleName}: Failed to resolve stateStore.payloadDiviner`)\n    return DivinerWrapper.wrap(mod, this.account)\n  }\n\n  /**\n   * Retrieves the last state of the Diviner process. Used to recover state after\n   * preemptions, reboots, etc.\n   */\n  protected async retrieveState(): Promise<ModuleState<TState> | undefined> {\n    if (this._lastState) return this._lastState\n    let hash: string = ''\n    const diviner = await this.getBoundWitnessDivinerForStateStore()\n    const query = await new PayloadBuilder<BoundWitnessDivinerQueryPayload>({ schema: BoundWitnessDivinerQuerySchema })\n      .fields({\n        address: this.account.address,\n        limit: 1,\n        offset: 0,\n        order: 'desc',\n        payload_schemas: [ModuleStateSchema],\n      })\n      .build()\n    const boundWitnesses = await diviner.divine([query])\n    if (boundWitnesses.length > 0) {\n      const boundWitness = boundWitnesses[0]\n      if (isBoundWitness(boundWitness)) {\n        // Find the index for this address in the BoundWitness that is a ModuleState\n        hash = boundWitness.addresses\n          .map((address, index) => ({ address, index }))\n          .filter(({ address }) => address === this.account.address)\n          .reduce(\n            (prev, curr) => (boundWitness.payload_schemas?.[curr?.index] === ModuleStateSchema ? boundWitness.payload_hashes[curr?.index] : prev),\n            '',\n          )\n      }\n    }\n\n    // If we able to located the last state\n    if (hash) {\n      // Get last state\n      const archivist = await this.getArchivistForStateStore()\n      const payload = (await archivist.get([hash])).find(isModuleState<TState>)\n      if (payload) {\n        return payload\n      }\n    }\n    return undefined\n  }\n}\n","import { assertEx } from '@xylabs/assert'\nimport { asArchivistInstance } from '@xyo-network/archivist'\nimport { BoundWitnessBuilder } from '@xyo-network/boundwitness-builder'\nimport { isBoundWitness } from '@xyo-network/boundwitness-model'\nimport { BoundWitnessDivinerQueryPayload, BoundWitnessDivinerQuerySchema } from '@xyo-network/diviner-boundwitness-model'\nimport { asDivinerInstance } from '@xyo-network/diviner-model'\nimport {\n  AnyConfigSchema,\n  isModuleState,\n  ModuleInstance,\n  ModuleParams,\n  ModuleState,\n  ModuleStateSchema,\n  StateDictionary,\n} from '@xyo-network/module-model'\nimport { PayloadBuilder } from '@xyo-network/payload-builder'\n\nimport { StatefulDivinerConfig } from './Config'\n\nexport type StatefulModuleParams = ModuleParams<AnyConfigSchema<StatefulDivinerConfig>>\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type AnyModule<TParams extends StatefulModuleParams = StatefulModuleParams> = new (...args: any[]) => ModuleInstance<TParams>\n\nconst moduleName = 'StatefulModuleMixin'\n\n/**\n * @ignore Inherit from StatefulDiviner instead\n * @param ModuleBase\n * @returns\n */\nexport const StatefulModuleMixin = <\n  TParams extends StatefulModuleParams = StatefulModuleParams,\n  TModule extends AnyModule<TParams> = AnyModule<TParams>,\n  TState extends StateDictionary = StateDictionary,\n>(\n  ModuleBase: TModule,\n) => {\n  abstract class StatefulModuleBase extends ModuleBase {\n    _lastState?: ModuleState<TState>\n\n    /**\n     * Commit the internal state of the Diviner process. This is similar\n     * to a transaction completion in a database and should only be called\n     * when results have been successfully persisted to the appropriate\n     * external stores.\n     * @param nextState The state to commit\n     */\n    async commitState(nextState: ModuleState<TState>) {\n      // Don't commit state if no state has changed\n      if (nextState.state.offset === this._lastState?.state.offset) return\n      this._lastState = nextState\n      const archivist = await this.getArchivistForStore()\n      // const [bw] = await new BoundWitnessBuilder().payload(nextState).witness(this.account).build()\n      const [bw] = await new BoundWitnessBuilder().payload(nextState).build()\n      await archivist.insert([bw, nextState])\n    }\n\n    /**\n     * Retrieves the archivist for the specified store\n     * @param store The store to retrieve the archivist for\n     * @returns The archivist for the specified store\n     */\n    async getArchivistForStore() {\n      const name = assertEx(this.config?.stateStore?.archivist, () => `${moduleName}: Config for stateStore.archivist not specified`)\n      const mod = assertEx(await this.resolve(name), () => `${moduleName}: Failed to resolve stateStore.archivist`)\n      // return ArchivistWrapper.wrap(mod, this.account)\n      const instance = asArchivistInstance(mod)\n      return assertEx(instance, () => `${moduleName}: Failed to wrap archivist instance`)\n    }\n\n    /**\n     * Retrieves the BoundWitness Diviner for the specified store\n     * @param store The store to retrieve the BoundWitness Diviner for\n     * @returns The BoundWitness Diviner for the specified store\n     */\n    async getBoundWitnessDivinerForStore() {\n      const name = assertEx(\n        this.config?.stateStore?.boundWitnessDiviner,\n        () => `${moduleName}: Config for stateStore.boundWitnessDiviner not specified`,\n      )\n      const mod = assertEx(await this.resolve(name), () => `${moduleName}: Failed to resolve stateStore.boundWitnessDiviner`)\n      // return DivinerWrapper.wrap(mod, this.account)\n      const instance = asDivinerInstance(mod)\n      return assertEx(instance, () => `${moduleName}: Failed to wrap diviner instance`)\n    }\n    /**\n     * Retrieves the Payload Diviner for the specified store\n     * @param store The store to retrieve the Payload Diviner for\n     * @returns The Payload Diviner for the specified store\n     */\n    async getPayloadDivinerForStateStore() {\n      const name = assertEx(this.config?.stateStore?.payloadDiviner, () => `${moduleName}: Config for stateStore.payloadDiviner not specified`)\n      const mod = assertEx(await this.resolve(name), () => `${moduleName}: Failed to resolve stateStore.payloadDiviner`)\n      // return DivinerWrapper.wrap(mod, this.account)\n      const instance = asDivinerInstance(mod)\n      return assertEx(instance, () => `${moduleName}: Failed to wrap diviner instance`)\n    }\n    /**\n     * Retrieves the last state of the Diviner process. Used to recover state after\n     * preemptions, reboots, etc.\n     */\n    async retrieveState(): Promise<ModuleState<TState> | undefined> {\n      if (this._lastState) return this._lastState\n      let hash: string = ''\n      const diviner = await this.getBoundWitnessDivinerForStore()\n      const query = await new PayloadBuilder<BoundWitnessDivinerQueryPayload>({ schema: BoundWitnessDivinerQuerySchema })\n        .fields({\n          // address: this.account.address,\n          limit: 1,\n          offset: 0,\n          order: 'desc',\n          payload_schemas: [ModuleStateSchema],\n        })\n        .build()\n      const boundWitnesses = await diviner.divine([query])\n      if (boundWitnesses.length > 0) {\n        const boundWitness = boundWitnesses[0]\n        if (isBoundWitness(boundWitness)) {\n          // Find the index for this address in the BoundWitness that is a ModuleState\n          hash = boundWitness.addresses\n            .map((address, index) => ({ address, index }))\n            // .filter(({ address }) => address === this.account.address)\n            .reduce(\n              (prev, curr) => (boundWitness.payload_schemas?.[curr?.index] === ModuleStateSchema ? boundWitness.payload_hashes[curr?.index] : prev),\n              '',\n            )\n        }\n      }\n\n      // If we able to located the last state\n      if (hash) {\n        // Get last state\n        const archivist = await this.getArchivistForStore()\n        const payload = (await archivist.get([hash])).find(isModuleState<TState>)\n        if (payload) {\n          return payload\n        }\n      }\n      return undefined\n    }\n  }\n  return StatefulModuleBase\n}\n"],"mappings":"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","names":["assertEx","BoundWitnessBuilder","isBoundWitness","BoundWitnessDivinerQuerySchema","isModuleState","ModuleStateSchema","PayloadBuilder","moduleName"]}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@xyo-network/diviner-stateful",
+  "author": {
+    "email": "support@xyo.network",
+    "name": "XYO Development Team",
+    "url": "https://xyo.network"
+  },
+  "bugs": {
+    "email": "support@xyo.network",
+    "url": "https://github.com/XYOracleNetwork/sdk-xyo-client-js/issues"
+  },
+  "dependencies": {
+    "@xylabs/assert": "^2.13.20",
+    "@xyo-network/abstract-diviner": "~2.84.1",
+    "@xyo-network/archivist": "~2.84.1",
+    "@xyo-network/archivist-wrapper": "~2.84.1",
+    "@xyo-network/boundwitness-builder": "~2.84.1",
+    "@xyo-network/boundwitness-model": "~2.84.1",
+    "@xyo-network/diviner-boundwitness-model": "~2.84.1",
+    "@xyo-network/diviner-model": "~2.84.1",
+    "@xyo-network/diviner-wrapper": "~2.84.1",
+    "@xyo-network/module-model": "~2.84.1",
+    "@xyo-network/payload-builder": "~2.84.1",
+    "@xyo-network/payload-model": "~2.84.1"
+  },
+  "devDependencies": {
+    "@xylabs/ts-scripts-yarn3": "^3.2.10",
+    "@xylabs/tsconfig": "^3.2.10",
+    "@xyo-network/account": "~2.84.1",
+    "@xyo-network/diviner-boundwitness-memory": "~2.84.1",
+    "@xyo-network/diviner-payload-memory": "~2.84.1",
+    "@xyo-network/manifest": "~2.84.1",
+    "@xyo-network/memory-archivist": "~2.84.1",
+    "@xyo-network/node-memory": "~2.84.1",
+    "typescript": "^5.3.3"
+  },
+  "description": "Primary SDK for using XYO Protocol 2.0",
+  "docs": "dist/docs.json",
+  "types": "dist/node/index.d.ts",
+  "exports": {
+    ".": {
+      "browser": {
+        "require": {
+          "types": "./dist/browser/index.d.cts",
+          "default": "./dist/browser/index.cjs"
+        },
+        "import": {
+          "types": "./dist/browser/index.d.mts",
+          "default": "./dist/browser/index.js"
+        }
+      },
+      "node": {
+        "require": {
+          "types": "./dist/node/index.d.ts",
+          "default": "./dist/node/index.js"
+        },
+        "import": {
+          "types": "./dist/node/index.d.mts",
+          "default": "./dist/node/index.mjs"
+        }
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "dist/node/index.js",
+  "module": "dist/node/index.mjs",
+  "homepage": "https://xyo.network",
+  "license": "LGPL-3.0-only",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/XYOracleNetwork/sdk-xyo-client-js.git"
+  },
+  "sideEffects": false,
+  "version": "2.84.1"
+}

package/src/Config.ts

@@ -0,0 +1,24 @@
+import { DivinerConfig } from '@xyo-network/diviner-model'
+
+import { StatefulDivinerSchema } from './Schema'
+
+/**
+ * The schema for a Stateful Diviner config
+ */
+export const StatefulDivinerConfigSchema = `${StatefulDivinerSchema}.config` as const
+/**
+ * The schema for a Stateful Diviner config
+ */
+export type StatefulDivinerConfigSchema = typeof StatefulDivinerConfigSchema
+
+/**
+ * The config for a Stateful Diviner
+ */
+export type StatefulDivinerConfig = DivinerConfig<{
+  schema: StatefulDivinerConfigSchema
+  stateStore: {
+    archivist: string
+    boundWitnessDiviner: string
+    payloadDiviner: string
+  }
+}>

package/src/Diviner.ts

@@ -0,0 +1,127 @@
+import { assertEx } from '@xylabs/assert'
+import { AbstractDiviner } from '@xyo-network/abstract-diviner'
+import { ArchivistWrapper } from '@xyo-network/archivist-wrapper'
+import { BoundWitnessBuilder } from '@xyo-network/boundwitness-builder'
+import { isBoundWitness } from '@xyo-network/boundwitness-model'
+import { BoundWitnessDivinerQueryPayload, BoundWitnessDivinerQuerySchema } from '@xyo-network/diviner-boundwitness-model'
+import { DivinerConfigSchema, DivinerModule, DivinerModuleEventData } from '@xyo-network/diviner-model'
+import { DivinerWrapper } from '@xyo-network/diviner-wrapper'
+import { isModuleState, ModuleState, ModuleStateSchema, StateDictionary } from '@xyo-network/module-model'
+import { PayloadBuilder } from '@xyo-network/payload-builder'
+import { Payload } from '@xyo-network/payload-model'
+
+import { StatefulDivinerConfigSchema } from './Config'
+import { StatefulDivinerParams } from './Params'
+
+const moduleName = 'StatefulDiviner'
+
+/**
+ * A Diviner that maintains state
+ */
+export abstract class StatefulDiviner<
+  TParams extends StatefulDivinerParams = StatefulDivinerParams,
+  TIn extends Payload = Payload,
+  TOut extends Payload = Payload,
+  TEventData extends DivinerModuleEventData<DivinerModule<TParams>, TIn, TOut> = DivinerModuleEventData<DivinerModule<TParams>, TIn, TOut>,
+  TState extends StateDictionary = StateDictionary,
+> extends AbstractDiviner<TParams, TIn, TOut, TEventData> {
+  static override readonly configSchemas: string[] = [DivinerConfigSchema, StatefulDivinerConfigSchema]
+
+  /**
+   * The last state
+   */
+  protected _lastState?: ModuleState<TState>
+
+  /**
+   * Commit the internal state of the Diviner process. This is similar
+   * to a transaction completion in a database and should only be called
+   * when results have been successfully persisted to the appropriate
+   * external stores.
+   * @param nextState The state to commit
+   */
+  protected async commitState(nextState: ModuleState<TState>) {
+    // Don't commit state if no state has changed
+    if (nextState.state.offset === this._lastState?.state.offset) return
+    this._lastState = nextState
+    const archivist = await this.getArchivistForStateStore()
+    const [bw] = await new BoundWitnessBuilder().payload(nextState).witness(this.account).build()
+    await archivist.insert([bw, nextState])
+  }
+
+  /**
+   * Retrieves the archivist for the specified store
+   * @param store The store to retrieve the archivist for
+   * @returns The archivist for the specified store
+   */
+  protected async getArchivistForStateStore() {
+    const name = assertEx(this.config?.stateStore.archivist, () => `${moduleName}: Config for stateStore.archivist not specified`)
+    const mod = assertEx(await this.resolve(name), () => `${moduleName}: Failed to resolve stateStore.archivist`)
+    return ArchivistWrapper.wrap(mod, this.account)
+  }
+
+  /**
+   * Retrieves the BoundWitness Diviner for the specified store
+   * @param store The store to retrieve the BoundWitness Diviner for
+   * @returns The BoundWitness Diviner for the specified store
+   */
+  protected async getBoundWitnessDivinerForStateStore() {
+    const name = assertEx(this.config?.stateStore.boundWitnessDiviner, () => `${moduleName}: Config for stateStore.boundWitnessDiviner not specified`)
+    const mod = assertEx(await this.resolve(name), () => `${moduleName}: Failed to resolve stateStore.boundWitnessDiviner`)
+    return DivinerWrapper.wrap(mod, this.account)
+  }
+
+  /**
+   * Retrieves the Payload Diviner for the specified store
+   * @param store The store to retrieve the Payload Diviner for
+   * @returns The Payload Diviner for the specified store
+   */
+  protected async getPayloadDivinerForStateStore() {
+    const name = assertEx(this.config?.stateStore?.payloadDiviner, () => `${moduleName}: Config for stateStore.payloadDiviner not specified`)
+    const mod = assertEx(await this.resolve(name), () => `${moduleName}: Failed to resolve stateStore.payloadDiviner`)
+    return DivinerWrapper.wrap(mod, this.account)
+  }
+
+  /**
+   * Retrieves the last state of the Diviner process. Used to recover state after
+   * preemptions, reboots, etc.
+   */
+  protected async retrieveState(): Promise<ModuleState<TState> | undefined> {
+    if (this._lastState) return this._lastState
+    let hash: string = ''
+    const diviner = await this.getBoundWitnessDivinerForStateStore()
+    const query = await new PayloadBuilder<BoundWitnessDivinerQueryPayload>({ schema: BoundWitnessDivinerQuerySchema })
+      .fields({
+        address: this.account.address,
+        limit: 1,
+        offset: 0,
+        order: 'desc',
+        payload_schemas: [ModuleStateSchema],
+      })
+      .build()
+    const boundWitnesses = await diviner.divine([query])
+    if (boundWitnesses.length > 0) {
+      const boundWitness = boundWitnesses[0]
+      if (isBoundWitness(boundWitness)) {
+        // Find the index for this address in the BoundWitness that is a ModuleState
+        hash = boundWitness.addresses
+          .map((address, index) => ({ address, index }))
+          .filter(({ address }) => address === this.account.address)
+          .reduce(
+            (prev, curr) => (boundWitness.payload_schemas?.[curr?.index] === ModuleStateSchema ? boundWitness.payload_hashes[curr?.index] : prev),
+            '',
+          )
+      }
+    }
+
+    // If we able to located the last state
+    if (hash) {
+      // Get last state
+      const archivist = await this.getArchivistForStateStore()
+      const payload = (await archivist.get([hash])).find(isModuleState<TState>)
+      if (payload) {
+        return payload
+      }
+    }
+    return undefined
+  }
+}

package/src/DivinerMixin.ts

@@ -0,0 +1,144 @@
+import { assertEx } from '@xylabs/assert'
+import { asArchivistInstance } from '@xyo-network/archivist'
+import { BoundWitnessBuilder } from '@xyo-network/boundwitness-builder'
+import { isBoundWitness } from '@xyo-network/boundwitness-model'
+import { BoundWitnessDivinerQueryPayload, BoundWitnessDivinerQuerySchema } from '@xyo-network/diviner-boundwitness-model'
+import { asDivinerInstance } from '@xyo-network/diviner-model'
+import {
+  AnyConfigSchema,
+  isModuleState,
+  ModuleInstance,
+  ModuleParams,
+  ModuleState,
+  ModuleStateSchema,
+  StateDictionary,
+} from '@xyo-network/module-model'
+import { PayloadBuilder } from '@xyo-network/payload-builder'
+
+import { StatefulDivinerConfig } from './Config'
+
+export type StatefulModuleParams = ModuleParams<AnyConfigSchema<StatefulDivinerConfig>>
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyModule<TParams extends StatefulModuleParams = StatefulModuleParams> = new (...args: any[]) => ModuleInstance<TParams>
+
+const moduleName = 'StatefulModuleMixin'
+
+/**
+ * @ignore Inherit from StatefulDiviner instead
+ * @param ModuleBase
+ * @returns
+ */
+export const StatefulModuleMixin = <
+  TParams extends StatefulModuleParams = StatefulModuleParams,
+  TModule extends AnyModule<TParams> = AnyModule<TParams>,
+  TState extends StateDictionary = StateDictionary,
+>(
+  ModuleBase: TModule,
+) => {
+  abstract class StatefulModuleBase extends ModuleBase {
+    _lastState?: ModuleState<TState>
+
+    /**
+     * Commit the internal state of the Diviner process. This is similar
+     * to a transaction completion in a database and should only be called
+     * when results have been successfully persisted to the appropriate
+     * external stores.
+     * @param nextState The state to commit
+     */
+    async commitState(nextState: ModuleState<TState>) {
+      // Don't commit state if no state has changed
+      if (nextState.state.offset === this._lastState?.state.offset) return
+      this._lastState = nextState
+      const archivist = await this.getArchivistForStore()
+      // const [bw] = await new BoundWitnessBuilder().payload(nextState).witness(this.account).build()
+      const [bw] = await new BoundWitnessBuilder().payload(nextState).build()
+      await archivist.insert([bw, nextState])
+    }
+
+    /**
+     * Retrieves the archivist for the specified store
+     * @param store The store to retrieve the archivist for
+     * @returns The archivist for the specified store
+     */
+    async getArchivistForStore() {
+      const name = assertEx(this.config?.stateStore?.archivist, () => `${moduleName}: Config for stateStore.archivist not specified`)
+      const mod = assertEx(await this.resolve(name), () => `${moduleName}: Failed to resolve stateStore.archivist`)
+      // return ArchivistWrapper.wrap(mod, this.account)
+      const instance = asArchivistInstance(mod)
+      return assertEx(instance, () => `${moduleName}: Failed to wrap archivist instance`)
+    }
+
+    /**
+     * Retrieves the BoundWitness Diviner for the specified store
+     * @param store The store to retrieve the BoundWitness Diviner for
+     * @returns The BoundWitness Diviner for the specified store
+     */
+    async getBoundWitnessDivinerForStore() {
+      const name = assertEx(
+        this.config?.stateStore?.boundWitnessDiviner,
+        () => `${moduleName}: Config for stateStore.boundWitnessDiviner not specified`,
+      )
+      const mod = assertEx(await this.resolve(name), () => `${moduleName}: Failed to resolve stateStore.boundWitnessDiviner`)
+      // return DivinerWrapper.wrap(mod, this.account)
+      const instance = asDivinerInstance(mod)
+      return assertEx(instance, () => `${moduleName}: Failed to wrap diviner instance`)
+    }
+    /**
+     * Retrieves the Payload Diviner for the specified store
+     * @param store The store to retrieve the Payload Diviner for
+     * @returns The Payload Diviner for the specified store
+     */
+    async getPayloadDivinerForStateStore() {
+      const name = assertEx(this.config?.stateStore?.payloadDiviner, () => `${moduleName}: Config for stateStore.payloadDiviner not specified`)
+      const mod = assertEx(await this.resolve(name), () => `${moduleName}: Failed to resolve stateStore.payloadDiviner`)
+      // return DivinerWrapper.wrap(mod, this.account)
+      const instance = asDivinerInstance(mod)
+      return assertEx(instance, () => `${moduleName}: Failed to wrap diviner instance`)
+    }
+    /**
+     * Retrieves the last state of the Diviner process. Used to recover state after
+     * preemptions, reboots, etc.
+     */
+    async retrieveState(): Promise<ModuleState<TState> | undefined> {
+      if (this._lastState) return this._lastState
+      let hash: string = ''
+      const diviner = await this.getBoundWitnessDivinerForStore()
+      const query = await new PayloadBuilder<BoundWitnessDivinerQueryPayload>({ schema: BoundWitnessDivinerQuerySchema })
+        .fields({
+          // address: this.account.address,
+          limit: 1,
+          offset: 0,
+          order: 'desc',
+          payload_schemas: [ModuleStateSchema],
+        })
+        .build()
+      const boundWitnesses = await diviner.divine([query])
+      if (boundWitnesses.length > 0) {
+        const boundWitness = boundWitnesses[0]
+        if (isBoundWitness(boundWitness)) {
+          // Find the index for this address in the BoundWitness that is a ModuleState
+          hash = boundWitness.addresses
+            .map((address, index) => ({ address, index }))
+            // .filter(({ address }) => address === this.account.address)
+            .reduce(
+              (prev, curr) => (boundWitness.payload_schemas?.[curr?.index] === ModuleStateSchema ? boundWitness.payload_hashes[curr?.index] : prev),
+              '',
+            )
+        }
+      }
+
+      // If we able to located the last state
+      if (hash) {
+        // Get last state
+        const archivist = await this.getArchivistForStore()
+        const payload = (await archivist.get([hash])).find(isModuleState<TState>)
+        if (payload) {
+          return payload
+        }
+      }
+      return undefined
+    }
+  }
+  return StatefulModuleBase
+}

package/src/Params.ts

@@ -0,0 +1,9 @@
+import { DivinerParams } from '@xyo-network/diviner-model'
+import { AnyConfigSchema } from '@xyo-network/module-model'
+
+import { StatefulDivinerConfig } from './Config'
+
+/**
+ * The parameters for a Stateful Diviner
+ */
+export type StatefulDivinerParams = DivinerParams<AnyConfigSchema<StatefulDivinerConfig>>

package/src/Schema.ts

@@ -0,0 +1,2 @@
+export const StatefulDivinerSchema = 'network.xyo.diviner.stateful' as const
+export type StatefulDivinerSchema = typeof StatefulDivinerSchema

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './Config'
+export * from './Diviner'
+export * from './DivinerMixin'
+export * from './Params'
+export * from './Schema'

package/src/spec/TestManifest.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://raw.githubusercontent.com/XYOracleNetwork/sdk-xyo-client-js/main/packages/manifest/src/schema.json",
+  "nodes": [
+    {
+      "config": {
+        "name": "DivinerTest",
+        "schema": "network.xyo.node.config"
+      },
+      "modules": {
+        "public": [
+          {
+            "config": {
+              "language": "javascript",
+              "name": "AddressStateArchivist",
+              "schema": "network.xyo.archivist.config"
+            }
+          },
+          {
+            "config": {
+              "archivist": "AddressStateArchivist",
+              "language": "javascript",
+              "name": "AddressStateBoundWitnessDiviner",
+              "schema": "network.xyo.diviner.boundwitness.config"
+            }
+          },
+          {
+            "config": {
+              "archivist": "AddressStateArchivist",
+              "language": "javascript",
+              "name": "AddressStatePayloadDiviner",
+              "schema": "network.xyo.diviner.payload.config"
+            }
+          },
+          {
+            "config": {
+              "language": "javascript",
+              "name": "Diviner",
+              "schema": "network.xyo.diviner.stateful.config",
+              "stateStore": {
+                "archivist": "AddressStateArchivist",
+                "boundWitnessDiviner": "AddressStateBoundWitnessDiviner",
+                "payloadDiviner": "AddressStatePayloadDiviner"
+              }
+            }
+          }
+        ]
+      }
+    }
+  ],
+  "schema": "network.xyo.manifest"
+}

package/typedoc.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["src/index.ts"],
+  "tsconfig": "./tsconfig.typedoc.json"
+}