@midnight-ntwrk/wallet-sdk-abstractions 2.0.0 → 2.1.0

package/dist/InMemoryTransactionHistoryStorage.d.ts

@@ -0,0 +1,27 @@
+import { Schema } from 'effect';
+import { type TransactionHistoryStorage, type TransactionHash, type TransactionHistoryCommon, type SerializedTransactionHistory } from './TransactionHistoryStorage.js';
+/**
+ * In-memory implementation of the TransactionHistoryStorage interface.
+ *
+ * An optional `merge` function can be provided to control how existing and incoming entries are combined during
+ * {@link upsert}. When omitted the default behaviour is a shallow spread (`{ ...existing, ...incoming }`).
+ *
+ * Because the merge runs **synchronously** inside `upsert`, the single-threaded nature of JavaScript guarantees
+ * atomicity — no external semaphore is needed.
+ */
+export declare class InMemoryTransactionHistoryStorage<T extends {
+    hash: TransactionHash;
+} = TransactionHistoryCommon, I = T> implements TransactionHistoryStorage<T> {
+    private storage;
+    private readonly schema;
+    private readonly merge;
+    constructor(schema: Schema.Schema<T, I>, merge?: (existing: T, incoming: T) => T);
+    upsert(entry: T): Promise<void>;
+    getAll(): Promise<readonly T[]>;
+    get(hash: TransactionHash): Promise<T | undefined>;
+    reset(): void;
+    serialize(): Promise<SerializedTransactionHistory>;
+    static restore<T extends {
+        hash: string;
+    }, I>(serialized: SerializedTransactionHistory, schema: Schema.Schema<T, I>, merge?: (existing: T, incoming: T) => T): InMemoryTransactionHistoryStorage<T, I>;
+}

package/dist/InMemoryTransactionHistoryStorage.js

@@ -0,0 +1,60 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// Licensed under the Apache License, Version 2.0 (the "License");
+// You may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import { Schema } from 'effect';
+/**
+ * In-memory implementation of the TransactionHistoryStorage interface.
+ *
+ * An optional `merge` function can be provided to control how existing and incoming entries are combined during
+ * {@link upsert}. When omitted the default behaviour is a shallow spread (`{ ...existing, ...incoming }`).
+ *
+ * Because the merge runs **synchronously** inside `upsert`, the single-threaded nature of JavaScript guarantees
+ * atomicity — no external semaphore is needed.
+ */
+export class InMemoryTransactionHistoryStorage {
+    storage;
+    schema;
+    merge;
+    constructor(schema, merge) {
+        this.storage = new Map();
+        this.schema = schema;
+        this.merge = merge ?? ((existing, incoming) => ({ ...existing, ...incoming }));
+    }
+    upsert(entry) {
+        const existing = this.storage.get(entry.hash);
+        this.storage.set(entry.hash, existing ? this.merge(existing, entry) : entry);
+        return Promise.resolve();
+    }
+    getAll() {
+        return Array.fromAsync(this.storage.values());
+    }
+    get(hash) {
+        return Promise.resolve(this.storage.get(hash));
+    }
+    reset() {
+        this.storage.clear();
+    }
+    async serialize() {
+        const allEntries = await this.getAll();
+        const encode = Schema.encodeSync(Schema.Array(this.schema));
+        return JSON.stringify(encode([...allEntries]));
+    }
+    static restore(serialized, schema, merge) {
+        const decode = Schema.decodeUnknownSync(Schema.Array(schema));
+        const decoded = decode(JSON.parse(serialized));
+        const storage = new InMemoryTransactionHistoryStorage(schema, merge);
+        for (const entry of decoded) {
+            storage.storage.set(entry.hash, entry);
+        }
+        return storage;
+    }
+}

package/dist/NoOpTransactionHistoryStorage.d.ts

@@ -0,0 +1,9 @@
+import { type TransactionHistoryStorage, type TransactionHash, type TransactionHistoryCommon, type SerializedTransactionHistory } from './TransactionHistoryStorage.js';
+export declare class NoOpTransactionHistoryStorage<T extends {
+    hash: TransactionHash;
+} = TransactionHistoryCommon> implements TransactionHistoryStorage<T> {
+    upsert(_entry: T): Promise<void>;
+    getAll(): Promise<readonly T[]>;
+    get(_hash: TransactionHash): Promise<T | undefined>;
+    serialize(): Promise<SerializedTransactionHistory>;
+}

package/dist/NoOpTransactionHistoryStorage.js

@@ -0,0 +1,14 @@
+export class NoOpTransactionHistoryStorage {
+    upsert(_entry) {
+        return Promise.resolve();
+    }
+    getAll() {
+        return Promise.resolve([]);
+    }
+    get(_hash) {
+        return Promise.resolve(undefined);
+    }
+    serialize() {
+        return Promise.resolve('[]');
+    }
+}

package/dist/ProtocolState.d.ts

@@ -1,4 +1,4 @@
-import * as ProtocolVersion from './ProtocolVersion.js';
+import type * as ProtocolVersion from './ProtocolVersion.js';
 /**
  * A type that associates some state with a given version of the Midnight protocol.
  *

package/dist/ProtocolVersion.d.ts

@@ -1,17 +1,11 @@
 import * as Brand from 'effect/Brand';
 import * as Schema from 'effect/Schema';
-/**
- * A branded `bigint` that represents a protocol version.
- */
+/** A branded `bigint` that represents a protocol version. */
 export type ProtocolVersion = Brand.Branded<bigint, 'ProtocolVersion'>;
-/**
- * Constructs a branded `bigint` represents a protocol version.
- */
+/** Constructs a branded `bigint` represents a protocol version. */
 export declare const ProtocolVersion: Brand.Brand.Constructor<ProtocolVersion>;
 export declare namespace ProtocolVersion {
-    /**
-     * A tuple type that represents a start and ending protocol version.
-     */
+    /** A tuple type that represents a start and ending protocol version. */
     type Range = readonly [start: ProtocolVersion, end: ProtocolVersion];
 }
 /**
@@ -20,9 +14,7 @@ export declare namespace ProtocolVersion {
  * @param start The start value.
  * @param end The end value.
  * @returns A {@link ProtocolVersion.Range} defined by `start` and `end`.
- *
- * @throws `TypeError`
- * Thrown when `start` is after `end`, or the difference between them is less than one.
+ * @throws `TypeError` Thrown when `start` is after `end`, or the difference between them is less than one.
  */
 export declare const makeRange: (start: ProtocolVersion, end: ProtocolVersion) => ProtocolVersion.Range;
 /**
@@ -33,9 +25,7 @@ export declare const makeRange: (start: ProtocolVersion, end: ProtocolVersion) =
  * @returns `true` if `version` is within the range defined by `range`.
  */
 export declare const withinRange: (version: ProtocolVersion, range: ProtocolVersion.Range) => boolean;
-/**
- * A schema that transforms a `bigint` into a {@link ProtocolVersion}.
- */
+/** A schema that transforms a `bigint` into a {@link ProtocolVersion}. */
 export declare const ProtocolVersionSchema: Schema.BrandSchema<bigint & Brand.Brand<"ProtocolVersion">, string, never>;
 /**
  * A type predicate that determines if a given value is a {@link ProtocolVersion}.
@@ -44,11 +34,7 @@ export declare const ProtocolVersionSchema: Schema.BrandSchema<bigint & Brand.Br
  * @returns `true` if `u` has the type {@link ProtocolVersion}.
  */
 export declare const is: (u: unknown, overrideOptions?: import("effect/SchemaAST").ParseOptions | number) => u is bigint & Brand.Brand<"ProtocolVersion">;
-/**
- * Represents the minimum supported protocol version.
- */
+/** Represents the minimum supported protocol version. */
 export declare const MinSupportedVersion: ProtocolVersion;
-/**
- * Represents the maximum supported protocol version.
- */
+/** Represents the maximum supported protocol version. */
 export declare const MaxSupportedVersion: ProtocolVersion;

package/dist/ProtocolVersion.js

@@ -12,9 +12,7 @@
 // limitations under the License.
 import * as Brand from 'effect/Brand';
 import * as Schema from 'effect/Schema';
-/**
- * Constructs a branded `bigint` represents a protocol version.
- */
+/** Constructs a branded `bigint` represents a protocol version. */
 export const ProtocolVersion = Brand.nominal();
 /**
  * Creates a new protocol version range.
@@ -22,9 +20,7 @@ export const ProtocolVersion = Brand.nominal();
  * @param start The start value.
  * @param end The end value.
  * @returns A {@link ProtocolVersion.Range} defined by `start` and `end`.
- *
- * @throws `TypeError`
- * Thrown when `start` is after `end`, or the difference between them is less than one.
+ * @throws `TypeError` Thrown when `start` is after `end`, or the difference between them is less than one.
  */
 // TODO: make it possible to represent an open range on the end side to remove special "MaxSupportedVersion"
 export const makeRange = (start, end) => {
@@ -43,9 +39,7 @@ export const withinRange = (version, range) => {
     const [min, max] = range;
     return version >= min && version < max;
 };
-/**
- * A schema that transforms a `bigint` into a {@link ProtocolVersion}.
- */
+/** A schema that transforms a `bigint` into a {@link ProtocolVersion}. */
 export const ProtocolVersionSchema = Schema.BigInt.pipe(Schema.fromBrand(ProtocolVersion));
 /**
  * A type predicate that determines if a given value is a {@link ProtocolVersion}.
@@ -54,11 +48,7 @@ export const ProtocolVersionSchema = Schema.BigInt.pipe(Schema.fromBrand(Protoco
  * @returns `true` if `u` has the type {@link ProtocolVersion}.
  */
 export const is = Schema.is(ProtocolVersionSchema);
-/**
- * Represents the minimum supported protocol version.
- */
+/** Represents the minimum supported protocol version. */
 export const MinSupportedVersion = ProtocolVersion(0n);
-/**
- * Represents the maximum supported protocol version.
- */
+/** Represents the maximum supported protocol version. */
 export const MaxSupportedVersion = ProtocolVersion(BigInt(Number.MAX_SAFE_INTEGER));

package/dist/SerializedTransaction.d.ts

@@ -1,11 +1,7 @@
 import * as Brand from 'effect/Brand';
-/**
- * A branded `Uint8Array` representing serialized transaction data.
- */
+/** A branded `Uint8Array` representing serialized transaction data. */
 export type SerializedTransaction = Brand.Branded<Uint8Array, 'SerializedTransaction'>;
-/**
- * Constructs a branded `Uint8Array` representing serialized transaction data.
- */
+/** Constructs a branded `Uint8Array` representing serialized transaction data. */
 export declare const SerializedTransaction: Brand.Brand.Constructor<SerializedTransaction>;
 export declare const of: (serialized: Uint8Array) => SerializedTransaction;
 export declare const from: <T extends {

package/dist/SerializedTransaction.js

@@ -11,9 +11,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 import * as Brand from 'effect/Brand';
-/**
- * Constructs a branded `Uint8Array` representing serialized transaction data.
- */
+/** Constructs a branded `Uint8Array` representing serialized transaction data. */
 export const SerializedTransaction = Brand.nominal();
 export const of = (serialized) => {
     return SerializedTransaction(serialized);

package/dist/TransactionHistoryStorage.d.ts

@@ -0,0 +1,33 @@
+import { Schema } from 'effect';
+export declare const TransactionHashSchema: typeof Schema.String;
+export type TransactionHash = Schema.Schema.Type<typeof TransactionHashSchema>;
+export declare const TransactionHistoryStatusSchema: Schema.Literal<["SUCCESS", "FAILURE", "PARTIAL_SUCCESS"]>;
+export type TransactionHistoryStatus = Schema.Schema.Type<typeof TransactionHistoryStatusSchema>;
+export declare const TransactionHistoryCommonSchema: Schema.Struct<{
+    hash: typeof Schema.String;
+    protocolVersion: typeof Schema.Number;
+    status: Schema.Literal<["SUCCESS", "FAILURE", "PARTIAL_SUCCESS"]>;
+    identifiers: Schema.optional<Schema.Array$<typeof Schema.String>>;
+    timestamp: Schema.optional<typeof Schema.Date>;
+    fees: Schema.optional<Schema.NullOr<typeof Schema.BigInt>>;
+}>;
+export type TransactionHistoryCommon = Schema.Schema.Type<typeof TransactionHistoryCommonSchema>;
+export type SerializedTransactionHistory = string;
+/**
+ * An entry with common fields plus any additional properties (wallet sections). Used by wallet packages for
+ * projection/filtering when the exact type is not known.
+ */
+export type TransactionHistoryEntryWithHash = TransactionHistoryCommon & Record<string, unknown>;
+/**
+ * Storage interface for transaction history entries keyed by their `hash` property.
+ *
+ * Pass a full entry schema to the implementation constructor to enable serialization.
+ */
+export interface TransactionHistoryStorage<T extends {
+    hash: TransactionHash;
+} = TransactionHistoryCommon> {
+    upsert(entry: T): Promise<void>;
+    getAll(): Promise<readonly T[]>;
+    get(hash: TransactionHash): Promise<T | undefined>;
+    serialize(): Promise<SerializedTransactionHistory>;
+}

package/dist/TransactionHistoryStorage.js

@@ -0,0 +1,23 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// Licensed under the Apache License, Version 2.0 (the "License");
+// You may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import { Schema } from 'effect';
+export const TransactionHashSchema = Schema.String;
+export const TransactionHistoryStatusSchema = Schema.Literal('SUCCESS', 'FAILURE', 'PARTIAL_SUCCESS');
+export const TransactionHistoryCommonSchema = Schema.Struct({
+    hash: TransactionHashSchema,
+    protocolVersion: Schema.Number,
+    status: TransactionHistoryStatusSchema,
+    identifiers: Schema.optional(Schema.Array(Schema.String)),
+    timestamp: Schema.optional(Schema.Date),
+    fees: Schema.optional(Schema.NullOr(Schema.BigInt)),
+});

package/dist/WalletSeed.d.ts

@@ -1,16 +1,10 @@
 import * as Brand from 'effect/Brand';
 import * as Schema from 'effect/Schema';
-/**
- * A branded `Uint8Array` that represents a BIP32 compatible seed phrase.
- */
+/** A branded `Uint8Array` that represents a BIP32 compatible seed phrase. */
 export type WalletSeed = Brand.Branded<Uint8Array, 'WalletSeed'>;
-/**
- * Constructs a branded `Uint8Array` representing a BIP32 compatible seed phrase.
- */
+/** Constructs a branded `Uint8Array` representing a BIP32 compatible seed phrase. */
 export declare const WalletSeed: Brand.Brand.Constructor<WalletSeed>;
-/**
- * A schema that transforms an array of numbers into a {@link WalletSeed}.
- */
+/** A schema that transforms an array of numbers into a {@link WalletSeed}. */
 export declare const WalletSeedSchema: Schema.BrandSchema<Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBufferLike> & Brand.Brand<"WalletSeed">, readonly number[], never>;
 /**
  * A type predicate that determines if a given value is a {@link WalletSeed}.

package/dist/WalletSeed.js

@@ -12,13 +12,9 @@
 // limitations under the License.
 import * as Brand from 'effect/Brand';
 import * as Schema from 'effect/Schema';
-/**
- * Constructs a branded `Uint8Array` representing a BIP32 compatible seed phrase.
- */
+/** Constructs a branded `Uint8Array` representing a BIP32 compatible seed phrase. */
 export const WalletSeed = Brand.nominal();
-/**
- * A schema that transforms an array of numbers into a {@link WalletSeed}.
- */
+/** A schema that transforms an array of numbers into a {@link WalletSeed}. */
 export const WalletSeedSchema = Schema.Uint8Array.pipe(Schema.fromBrand(WalletSeed));
 /**
  * A type predicate that determines if a given value is a {@link WalletSeed}.

package/dist/WalletState.d.ts

@@ -1,17 +1,13 @@
 import * as Brand from 'effect/Brand';
 import * as Schema from 'effect/Schema';
 /**
- * A branded `string` representing serialized (JSON) wallet state made up of local state, transaction history,
- * and block height.
+ * A branded `string` representing serialized (JSON) wallet state made up of local state, transaction history, and block
+ * height.
  */
 export type WalletState = Brand.Branded<string, 'WalletState'>;
-/**
- * Constructs a branded `string` representing serialized (JSON) wallet state.
- */
+/** Constructs a branded `string` representing serialized (JSON) wallet state. */
 export declare const WalletState: Brand.Brand.Constructor<WalletState>;
-/**
- * A schema that transforms a string into a {@link WalletState}.
- */
+/** A schema that transforms a string into a {@link WalletState}. */
 export declare const WalletStateSchema: Schema.BrandSchema<string & Brand.Brand<"WalletState">, string, never>;
 /**
  * A type predicate that determines if a given value is a {@link WalletState}.

package/dist/WalletState.js

@@ -12,13 +12,9 @@
 // limitations under the License.
 import * as Brand from 'effect/Brand';
 import * as Schema from 'effect/Schema';
-/**
- * Constructs a branded `string` representing serialized (JSON) wallet state.
- */
+/** Constructs a branded `string` representing serialized (JSON) wallet state. */
 export const WalletState = Brand.nominal();
-/**
- * A schema that transforms a string into a {@link WalletState}.
- */
+/** A schema that transforms a string into a {@link WalletState}. */
 export const WalletStateSchema = Schema.String.pipe(Schema.fromBrand(WalletState));
 /**
  * A type predicate that determines if a given value is a {@link WalletState}.

package/dist/index.d.ts

@@ -5,3 +5,6 @@ export * as ProtocolState from './ProtocolState.js';
 export * as ProtocolVersion from './ProtocolVersion.js';
 export * as NetworkId from './NetworkId.js';
 export * as SyncProgress from './SyncProgress.js';
+export * from './InMemoryTransactionHistoryStorage.js';
+export * from './NoOpTransactionHistoryStorage.js';
+export * as TransactionHistoryStorage from './TransactionHistoryStorage.js';

package/dist/index.js

@@ -17,3 +17,6 @@ export * as ProtocolState from './ProtocolState.js';
 export * as ProtocolVersion from './ProtocolVersion.js';
 export * as NetworkId from './NetworkId.js';
 export * as SyncProgress from './SyncProgress.js';
+export * from './InMemoryTransactionHistoryStorage.js';
+export * from './NoOpTransactionHistoryStorage.js';
+export * as TransactionHistoryStorage from './TransactionHistoryStorage.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@midnight-ntwrk/wallet-sdk-abstractions",
   "description": "Domain-specific abstractions for the wallet SDK",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",