@lucid-evolution/utils 0.1.75 → 0.2.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import * as _effect_schema_AST from '@effect/schema/AST';
 import { Script, Native, Network, Credential, RewardAddress, AddressDetails, CertificateValidator, WithdrawalValidator, DatumJson, Datum, ProtocolParameters, CostModels, Address, KeyHash, ScriptHash, DatumHash, PrivateKey, PublicKey, Exact, MintingPolicy, PolicyId, SpendingValidator, Validator, Slot, UnixTime, UTxO, OutRef, TxOutput, Assets, Unit, RedeemerTag } from '@lucid-evolution/core-types';
-import * as CML from '@anastasia-labs/cardano-multiplatform-lib-nodejs';
+import * as CML from '@lucid-evolution/cml';
 import { Data } from '@lucid-evolution/plutus';
 
 /**
@@ -93,6 +93,12 @@ declare function networkToId(network: Network): number;
 
 declare function validatorToAddress(network: Network, validator: SpendingValidator, stakeCredential?: Credential): Address;
 declare function validatorToScriptHash(validator: Validator): ScriptHash;
+/**
+ * The script's CBOR as CML reads it: the double CBOR encoded script
+ * (`applyDoubleCborEncoding`) for Plutus scripts, the script itself for native
+ * scripts. Returns a fresh copy.
+ */
+declare function scriptCborBytes(script: Script): Uint8Array;
 declare function toScriptRef(script: Script): CML.Script;
 declare function fromScriptRef(scriptRef: CML.Script): Script;
 declare function mintingPolicyToId(mintingPolicy: MintingPolicy): PolicyId;
@@ -103,6 +109,49 @@ declare function mintingPolicyToId(mintingPolicy: MintingPolicy): PolicyId;
  */
 declare function applyParamsToScript<T extends unknown[] = Data[]>(plutusScript: string, params: Exact<[...T]>, type?: T): string;
 
+/**
+ * Bounded memo tables keyed by script text.
+ *
+ * Script hex strings are long (a typical Plutus validator is 10-40k hex
+ * characters). V8 hashes a string longer than 16383 characters by its length
+ * alone, so a `Map` keyed by the script text puts every script of the same
+ * length in one hash bucket and a lookup can compare tens of kilobytes per
+ * entry. Parameterized validators make that common: every instance has the
+ * same length and differs only near the end. The tables here hash a short
+ * fingerprint of the script instead and confirm a hit by comparing the full
+ * text, keeping at most `MAX_CHAIN` scripts per fingerprint.
+ *
+ * Store only immutable values: strings, or byte arrays that are never handed
+ * to callers (return copies). Never store CML objects. Eviction is first-in
+ * first-out.
+ */
+/** A bounded memo table keyed by a namespace (such as the script type) and script text. */
+declare class ScriptCache<V> {
+    private readonly capacity;
+    private readonly maxWeight;
+    private readonly weigh;
+    private readonly buckets;
+    /** Insertion order, for first-in first-out eviction. */
+    private readonly order;
+    private totalWeight;
+    /**
+     * @param capacity maximum number of entries
+     * @param maxWeight maximum total weight, see `weigh`
+     * @param weigh approximate retained bytes of an entry besides its key
+     */
+    constructor(capacity: number, maxWeight: number, weigh?: (value: V) => number);
+    get size(): number;
+    get(namespace: string, script: string): V | undefined;
+    set(namespace: string, script: string, value: V): void;
+    clear(): void;
+    private remove;
+    /**
+     * Returns the cached value, or computes, stores and returns it. A `compute`
+     * that throws stores nothing.
+     */
+    getOrCompute(namespace: string, script: string, compute: () => V): V;
+}
+
 /**
  * Converts unix time to slot based on the network. For "Custom" network
  * it is advisable use `unixTimeToSlot` method from `LucidEvolution`
@@ -115,6 +164,10 @@ declare function applyParamsToScript<T extends unknown[] = Data[]>(plutusScript:
 declare function unixTimeToSlot(network: Network, unixTime: UnixTime): Slot;
 declare function slotToUnixTime(network: Network, slot: Slot): UnixTime;
 
+/**
+ * Builds the output directly rather than through `TransactionOutputBuilder`,
+ * whose every stage copies the datum and script; the result is the same.
+ */
 declare const utxoToTransactionOutput: (utxo: UTxO) => CML.TransactionOutput;
 declare const utxoToTransactionInput: (utxo: UTxO) => CML.TransactionInput;
 declare const utxoToCore: (utxo: UTxO) => CML.TransactionUnspentOutput;
@@ -205,4 +258,4 @@ declare const stringify: (data: any) => string;
 declare const toCMLRedeemerTag: (tag: string) => CML.RedeemerTag;
 declare const fromCMLRedeemerTag: (tag: CML.RedeemerTag) => RedeemerTag;
 
-export { CBOREncodingLevel, type CMLNative, PROTOCOL_PARAMETERS_DEFAULT, type SortOrder, addAssets, addressFromHexOrBech32, applyDoubleCborEncoding, applyParamsToScript, applySingleCborEncoding, assetsToValue, calculateMinLovelaceFromUTxO, coreToOutRef, coreToTxOutput, coreToUtxo, coresToOutRefs, coresToTxOutputs, coresToUtxos, createCostModels, credentialToAddress, credentialToRewardAddress, datumJsonToCbor, datumToHash, drepIDToCredential, fromCMLRedeemerTag, fromLabel, fromScriptRef, fromUnit, generatePrivateKey, generateSeedPhrase, getAddressDetails, getInputIndices, getUniqueTokenName, isEqualUTxO, keyHashToCredential, mintingPolicyToId, networkToId, parseCMLNative, paymentCredentialOf, scriptFromCMLNative, scriptFromNative, scriptHashToCredential, selectUTxOs, slotToUnixTime, sortCanonical, sortUTxOs, stakeCredentialOf, stringify, toCMLNativeScript, toCMLRedeemerTag, toLabel, toPublicKey, toScriptRef, toUnit, unixTimeToSlot, utxoToCore, utxoToTransactionInput, utxoToTransactionOutput, utxosToCores, validatorToAddress, validatorToRewardAddress, validatorToScriptHash, valueToAssets };
+export { CBOREncodingLevel, type CMLNative, PROTOCOL_PARAMETERS_DEFAULT, ScriptCache, type SortOrder, addAssets, addressFromHexOrBech32, applyDoubleCborEncoding, applyParamsToScript, applySingleCborEncoding, assetsToValue, calculateMinLovelaceFromUTxO, coreToOutRef, coreToTxOutput, coreToUtxo, coresToOutRefs, coresToTxOutputs, coresToUtxos, createCostModels, credentialToAddress, credentialToRewardAddress, datumJsonToCbor, datumToHash, drepIDToCredential, fromCMLRedeemerTag, fromLabel, fromScriptRef, fromUnit, generatePrivateKey, generateSeedPhrase, getAddressDetails, getInputIndices, getUniqueTokenName, isEqualUTxO, keyHashToCredential, mintingPolicyToId, networkToId, parseCMLNative, paymentCredentialOf, scriptCborBytes, scriptFromCMLNative, scriptFromNative, scriptHashToCredential, selectUTxOs, slotToUnixTime, sortCanonical, sortUTxOs, stakeCredentialOf, stringify, toCMLNativeScript, toCMLRedeemerTag, toLabel, toPublicKey, toScriptRef, toUnit, unixTimeToSlot, utxoToCore, utxoToTransactionInput, utxoToTransactionOutput, utxosToCores, validatorToAddress, validatorToRewardAddress, validatorToScriptHash, valueToAssets };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as _effect_schema_AST from '@effect/schema/AST';
 import { Script, Native, Network, Credential, RewardAddress, AddressDetails, CertificateValidator, WithdrawalValidator, DatumJson, Datum, ProtocolParameters, CostModels, Address, KeyHash, ScriptHash, DatumHash, PrivateKey, PublicKey, Exact, MintingPolicy, PolicyId, SpendingValidator, Validator, Slot, UnixTime, UTxO, OutRef, TxOutput, Assets, Unit, RedeemerTag } from '@lucid-evolution/core-types';
-import * as CML from '@anastasia-labs/cardano-multiplatform-lib-nodejs';
+import * as CML from '@lucid-evolution/cml';
 import { Data } from '@lucid-evolution/plutus';
 
 /**
@@ -93,6 +93,12 @@ declare function networkToId(network: Network): number;
 
 declare function validatorToAddress(network: Network, validator: SpendingValidator, stakeCredential?: Credential): Address;
 declare function validatorToScriptHash(validator: Validator): ScriptHash;
+/**
+ * The script's CBOR as CML reads it: the double CBOR encoded script
+ * (`applyDoubleCborEncoding`) for Plutus scripts, the script itself for native
+ * scripts. Returns a fresh copy.
+ */
+declare function scriptCborBytes(script: Script): Uint8Array;
 declare function toScriptRef(script: Script): CML.Script;
 declare function fromScriptRef(scriptRef: CML.Script): Script;
 declare function mintingPolicyToId(mintingPolicy: MintingPolicy): PolicyId;
@@ -103,6 +109,49 @@ declare function mintingPolicyToId(mintingPolicy: MintingPolicy): PolicyId;
  */
 declare function applyParamsToScript<T extends unknown[] = Data[]>(plutusScript: string, params: Exact<[...T]>, type?: T): string;
 
+/**
+ * Bounded memo tables keyed by script text.
+ *
+ * Script hex strings are long (a typical Plutus validator is 10-40k hex
+ * characters). V8 hashes a string longer than 16383 characters by its length
+ * alone, so a `Map` keyed by the script text puts every script of the same
+ * length in one hash bucket and a lookup can compare tens of kilobytes per
+ * entry. Parameterized validators make that common: every instance has the
+ * same length and differs only near the end. The tables here hash a short
+ * fingerprint of the script instead and confirm a hit by comparing the full
+ * text, keeping at most `MAX_CHAIN` scripts per fingerprint.
+ *
+ * Store only immutable values: strings, or byte arrays that are never handed
+ * to callers (return copies). Never store CML objects. Eviction is first-in
+ * first-out.
+ */
+/** A bounded memo table keyed by a namespace (such as the script type) and script text. */
+declare class ScriptCache<V> {
+    private readonly capacity;
+    private readonly maxWeight;
+    private readonly weigh;
+    private readonly buckets;
+    /** Insertion order, for first-in first-out eviction. */
+    private readonly order;
+    private totalWeight;
+    /**
+     * @param capacity maximum number of entries
+     * @param maxWeight maximum total weight, see `weigh`
+     * @param weigh approximate retained bytes of an entry besides its key
+     */
+    constructor(capacity: number, maxWeight: number, weigh?: (value: V) => number);
+    get size(): number;
+    get(namespace: string, script: string): V | undefined;
+    set(namespace: string, script: string, value: V): void;
+    clear(): void;
+    private remove;
+    /**
+     * Returns the cached value, or computes, stores and returns it. A `compute`
+     * that throws stores nothing.
+     */
+    getOrCompute(namespace: string, script: string, compute: () => V): V;
+}
+
 /**
  * Converts unix time to slot based on the network. For "Custom" network
  * it is advisable use `unixTimeToSlot` method from `LucidEvolution`
@@ -115,6 +164,10 @@ declare function applyParamsToScript<T extends unknown[] = Data[]>(plutusScript:
 declare function unixTimeToSlot(network: Network, unixTime: UnixTime): Slot;
 declare function slotToUnixTime(network: Network, slot: Slot): UnixTime;
 
+/**
+ * Builds the output directly rather than through `TransactionOutputBuilder`,
+ * whose every stage copies the datum and script; the result is the same.
+ */
 declare const utxoToTransactionOutput: (utxo: UTxO) => CML.TransactionOutput;
 declare const utxoToTransactionInput: (utxo: UTxO) => CML.TransactionInput;
 declare const utxoToCore: (utxo: UTxO) => CML.TransactionUnspentOutput;
@@ -205,4 +258,4 @@ declare const stringify: (data: any) => string;
 declare const toCMLRedeemerTag: (tag: string) => CML.RedeemerTag;
 declare const fromCMLRedeemerTag: (tag: CML.RedeemerTag) => RedeemerTag;
 
-export { CBOREncodingLevel, type CMLNative, PROTOCOL_PARAMETERS_DEFAULT, type SortOrder, addAssets, addressFromHexOrBech32, applyDoubleCborEncoding, applyParamsToScript, applySingleCborEncoding, assetsToValue, calculateMinLovelaceFromUTxO, coreToOutRef, coreToTxOutput, coreToUtxo, coresToOutRefs, coresToTxOutputs, coresToUtxos, createCostModels, credentialToAddress, credentialToRewardAddress, datumJsonToCbor, datumToHash, drepIDToCredential, fromCMLRedeemerTag, fromLabel, fromScriptRef, fromUnit, generatePrivateKey, generateSeedPhrase, getAddressDetails, getInputIndices, getUniqueTokenName, isEqualUTxO, keyHashToCredential, mintingPolicyToId, networkToId, parseCMLNative, paymentCredentialOf, scriptFromCMLNative, scriptFromNative, scriptHashToCredential, selectUTxOs, slotToUnixTime, sortCanonical, sortUTxOs, stakeCredentialOf, stringify, toCMLNativeScript, toCMLRedeemerTag, toLabel, toPublicKey, toScriptRef, toUnit, unixTimeToSlot, utxoToCore, utxoToTransactionInput, utxoToTransactionOutput, utxosToCores, validatorToAddress, validatorToRewardAddress, validatorToScriptHash, valueToAssets };
+export { CBOREncodingLevel, type CMLNative, PROTOCOL_PARAMETERS_DEFAULT, ScriptCache, type SortOrder, addAssets, addressFromHexOrBech32, applyDoubleCborEncoding, applyParamsToScript, applySingleCborEncoding, assetsToValue, calculateMinLovelaceFromUTxO, coreToOutRef, coreToTxOutput, coreToUtxo, coresToOutRefs, coresToTxOutputs, coresToUtxos, createCostModels, credentialToAddress, credentialToRewardAddress, datumJsonToCbor, datumToHash, drepIDToCredential, fromCMLRedeemerTag, fromLabel, fromScriptRef, fromUnit, generatePrivateKey, generateSeedPhrase, getAddressDetails, getInputIndices, getUniqueTokenName, isEqualUTxO, keyHashToCredential, mintingPolicyToId, networkToId, parseCMLNative, paymentCredentialOf, scriptCborBytes, scriptFromCMLNative, scriptFromNative, scriptHashToCredential, selectUTxOs, slotToUnixTime, sortCanonical, sortUTxOs, stakeCredentialOf, stringify, toCMLNativeScript, toCMLRedeemerTag, toLabel, toPublicKey, toScriptRef, toUnit, unixTimeToSlot, utxoToCore, utxoToTransactionInput, utxoToTransactionOutput, utxosToCores, validatorToAddress, validatorToRewardAddress, validatorToScriptHash, valueToAssets };