@harmoniclabs/pebble 0.1.0-dev0

package/dist/IR/IRNodes/IRLetted.js

@@ -0,0 +1,444 @@
+import { iterTree } from "../toUPLC/_internal/iterTree.js";
+import { IRVar } from "./IRVar.js";
+import { positiveIntAsBytes } from "../utils/positiveIntAsBytes.js";
+import { freezeAll } from "@harmoniclabs/obj-utils";
+import { BasePlutsError } from "../../utils/BasePlutsError.js";
+import { concatUint8Arr } from "../utils/concatUint8Arr.js";
+import { isIRTerm } from "../utils/isIRTerm.js";
+import { IRApp } from "./IRApp.js";
+import { IRDelayed } from "./IRDelayed.js";
+import { IRForced } from "./IRForced.js";
+import { IRFunc } from "./IRFunc.js";
+import { IRHoisted } from "./IRHoisted.js";
+import { isIRParentTerm } from "../utils/isIRParentTerm.js";
+import { _modifyChildFromTo } from "../toUPLC/_internal/_modifyChildFromTo.js";
+import { _getMinUnboundDbn } from "../toUPLC/subRoutines/handleLetted/groupByScope.js";
+import { IRConstr } from "./IRConstr.js";
+import { IRCase } from "./IRCase.js";
+import { equalIrHash, hashIrData, irHashToHex, isIRHash } from "../IRHash.js";
+import { shallowEqualIRTermHash } from "../utils/equalIRTerm.js";
+import { IRNodeKind } from "../IRNodeKind.js";
+import { IRRecursive } from "./IRRecursive.js";
+import { IRSelfCall } from "./IRSelfCall.js";
+export function jsonLettedSetEntry(entry) {
+    return {
+        letted: irHashToHex(entry.letted.hash),
+        nReferences: entry.nReferences
+    };
+}
+export function expandedJsonLettedSetEntry(entry) {
+    return {
+        letted: irHashToHex(entry.letted.hash),
+        // letted_value: prettyIR( entry.letted.value ).text.split("\n"),
+        nReferences: entry.nReferences
+    };
+}
+const defaultLettedMeta = freezeAll({
+    forceHoist: false,
+    __src__: undefined,
+    isClosed: false
+});
+let n_hash_access = 0;
+export class IRLetted {
+    _hash;
+    get hash() {
+        if (!isIRHash(this._hash)) {
+            /*
+            NOTE TO SELF:
+
+            NEVER
+            NEVER
+            NEVER
+
+            NEVER GET THE HASH BASED ON THE METADATA
+
+            NEVER
+            */
+            const normalized = getNormalizedLettedArgs(this.dbn, this._value);
+            if (normalized === undefined) {
+                // `_value` doesn't includes any `IRVar`
+                // aka. there is nothing to normalize
+                // just use the value regardless of the
+                // `IRLetted` dbn instantiation
+                this._hash = hashIrData(concatUint8Arr(IRLetted.tag, this._value.hash));
+            }
+            else {
+                this._hash = hashIrData(concatUint8Arr(IRLetted.tag, positiveIntAsBytes(normalized[0]), normalized[1].hash));
+                /*
+                const [ normalized_dbn, normalized_value] = normalized;
+                if( toHex( hash ) === "ee84fb036ed2726e01b0415109246927" )
+                {
+                    const original_value = _value.clone();
+                    const minDbn = getMinVarDbn( original_value );
+                    const minUnb = _getMinUnboundDbn( original_value );
+                    console.log(
+                        "_ee84fb036ed2726e01b0415109246927_",
+                        "\noriginal value:", prettyIRJsonStr( original_value, 2, { hoisted: false } ),
+                        "\nmin dbn:", minDbn,
+                        "\nmin unbound:", minUnb,
+                        "\nnormalized dbn:", normalized_dbn,
+                    );
+                }
+                //*/
+            }
+        }
+        return this._hash;
+    }
+    markHashAsInvalid() {
+        this._hash = undefined;
+        this._deps = undefined;
+        this.parent?.markHashAsInvalid();
+    }
+    isHashPresent() { return isIRHash(this._hash); }
+    _value;
+    get value() { return this._value; }
+    set value(newVal) {
+        if (!isIRTerm(newVal))
+            throw new BasePlutsError("letted term was not IRTerm");
+        if (!shallowEqualIRTermHash(this._value, newVal))
+            this.markHashAsInvalid();
+        // remove deps even if the value is the same
+        // newValue might be a clone of the current value
+        // and so have different (new) objects
+        this._deps = undefined;
+        // keep the parent reference in the old child, useful for compilation
+        // _value.parent = undefined;
+        this._value = newVal;
+        this._value.parent = this;
+    }
+    _dbn;
+    /**
+     * we need to keep track of the debruijn at which the `IRLetted` is instantiated
+     *
+     * this is because stuff like `new IRLetted( new IRVar(0) )` has different meaning
+     * at different DeBruijn levels
+     *
+     * knowing the DeBruijn we can differentiate them
+     */
+    get dbn() { return this._dbn; }
+    set dbn(newDbn) {
+        if (!(Number.isSafeInteger(newDbn) && newDbn >= 0))
+            throw new BasePlutsError("invalid index for an `IRLetted` instance");
+        if (newDbn === this._dbn) {
+            // everything ok
+            // avoid calling `markHashAsInvalid` 
+            return;
+        }
+        this.markHashAsInvalid();
+        this._dbn = newDbn;
+    }
+    isClosedAtDbn(dbn) {
+        if (!Number.isSafeInteger(dbn))
+            throw new Error("unexpected unsafe dbn integer");
+        const minUnbound = _getMinUnboundDbn(this._value);
+        if (minUnbound === undefined)
+            return true;
+        return minUnbound < dbn;
+    }
+    _deps;
+    get dependencies() {
+        if (this._deps === undefined)
+            this._deps = getSortedLettedSet(getLettedTerms(this._value));
+        return this._deps;
+    }
+    _parent;
+    get parent() { return this._parent; }
+    set parent(newParent) {
+        if (!( // assert
+        // new parent value is different than current
+        this._parent !== newParent && (
+        // and the new parent value is valid
+        newParent === undefined ||
+            isIRParentTerm(newParent))))
+            return;
+        this._parent = newParent;
+    }
+    meta;
+    constructor(DeBruijn, toLet, metadata = {}, _unsafeHash = undefined) {
+        DeBruijn = typeof DeBruijn === "bigint" ? Number(DeBruijn) : DeBruijn;
+        if (!(Number.isSafeInteger(DeBruijn) && DeBruijn >= 0))
+            throw new BasePlutsError("invalid index for an `IRLetted` instance");
+        while (toLet instanceof IRLetted ||
+            toLet instanceof IRHoisted) {
+            toLet = toLet instanceof IRLetted ? toLet.value : toLet.hoisted;
+        }
+        if (!isIRTerm(toLet))
+            throw new BasePlutsError("letted value was not an IRTerm");
+        this._dbn = DeBruijn;
+        this._value = toLet;
+        this._value.parent = this;
+        // we need the has before setting dependecies
+        this._hash = isIRHash(_unsafeHash) ? _unsafeHash : undefined;
+        this._deps = undefined;
+        this._parent = undefined;
+        this.meta = {
+            ...defaultLettedMeta,
+            ...metadata,
+            // isClosed: metadata.isClosed || this.isClosedAtDbn( 0 )
+        };
+    }
+    static get kind() { return IRNodeKind.Letted; }
+    get kind() { return IRLetted.kind; }
+    static get tag() { return new Uint8Array([IRLetted.kind]); }
+    clone() {
+        return new IRLetted(this.dbn, this.value.clone(), { ...this.meta }, this.isHashPresent() ? this.hash : undefined);
+    }
+    toJSON() { return this.toJson(); }
+    toJson() {
+        return {
+            type: "IRLetted",
+            hash: irHashToHex(this.hash),
+            value: this.value.toJson()
+        };
+    }
+}
+/**
+ * basically an insertion sort;
+ *
+ * @param {LettedSetEntry[]} lettedTerms
+ * @returns {LettedSetEntry[]} a **new** array with ```IRLetted```s with no dependencies first, followed by the dependents
+ */
+export function getSortedLettedSet(lettedTerms) {
+    const set = [];
+    const hashesSet = [];
+    /**
+     * **O((n * m) * d)**
+     *
+     * where
+     *
+     *      n = length of set
+     *      m = number of terms passed
+     *      d = number of unique dependencies among the passed terms
+     */
+    function addToSet(_terms) {
+        for (let i = 0; i < _terms.length; i++) {
+            const thisLettedEntry = _terms[i];
+            const thisHash = thisLettedEntry.letted.hash;
+            const idxInSet = hashesSet.findIndex(hash => equalIrHash(hash, thisHash));
+            // if( !hashesSet.includes( hash ) )
+            // "includes" uses standard equality (===)
+            if (idxInSet < 0) // not present
+             {
+                // add dependencies first
+                // dependencies don't have references to the current letted
+                // (of course, wouldn't be much of a dependecy otherwhise)
+                //
+                // don't add dependecies of dependecies since `dependecies` proerty
+                // already calls `getSortedLettedSet( getLettedTerms( _value ) )`
+                // so repeating it here would count deps twice (exponentially for deps of deps)
+                addToSet(getLettedTerms(thisLettedEntry.letted.value));
+                hashesSet.push(thisHash);
+                set.push({
+                    letted: thisLettedEntry.letted,
+                    nReferences: thisLettedEntry.nReferences
+                });
+            }
+            else {
+                const entry = set[idxInSet];
+                entry.nReferences += thisLettedEntry.nReferences;
+                entry.letted.meta.forceHoist =
+                    entry.letted.meta.forceHoist ||
+                        thisLettedEntry.letted.meta.forceHoist;
+            }
+        }
+    }
+    addToSet(lettedTerms);
+    return set;
+}
+export const default_getLettedTermsOptions = {
+    all: false,
+    includeHoisted: false
+};
+/**
+ *
+ * @param {IRTerm} irTerm term to search in
+ * @returns direct letted terms (no possible dependencies)
+ */
+export function getLettedTerms(irTerm, options) {
+    const { all, includeHoisted } = {
+        ...default_getLettedTermsOptions,
+        ...options
+    };
+    const lettedTerms = [];
+    const stack = [irTerm];
+    while (stack.length > 0) {
+        const t = stack.pop();
+        if (t instanceof IRLetted) {
+            lettedTerms.push({ letted: t, nReferences: 1 });
+            if (all) {
+                stack.push(t.value);
+            }
+            continue;
+        }
+        if (t instanceof IRApp) {
+            stack.push(t.fn, t.arg);
+            continue;
+        }
+        if (t instanceof IRConstr) {
+            stack.push(...Array.from(t.fields));
+            continue;
+        }
+        if (t instanceof IRCase) {
+            stack.push(t.constrTerm, ...Array.from(t.continuations));
+            continue;
+        }
+        if (t instanceof IRFunc) {
+            stack.push(t.body);
+            continue;
+        }
+        if (t instanceof IRRecursive) {
+            stack.push(t.body);
+            continue;
+        }
+        if (t instanceof IRForced) {
+            stack.push(t.forced);
+            continue;
+        }
+        if (t instanceof IRDelayed) {
+            stack.push(t.delayed);
+            continue;
+        }
+        if (includeHoisted) {
+            if (t instanceof IRHoisted) {
+                stack.push(t.hoisted);
+                continue;
+            }
+        }
+    }
+    return lettedTerms;
+}
+export function getNormalizedLettedArgs(lettedDbn, value) {
+    const normalized_value = value.clone();
+    const minDbn = getMinVarDbn(normalized_value);
+    if (minDbn === undefined)
+        return undefined;
+    if (minDbn !== 0)
+        iterTree(normalized_value, (node, relativeDbn) => {
+            if (node instanceof IRVar) {
+                node.dbn -= minDbn;
+            }
+            else if (node instanceof IRSelfCall) {
+                node.dbn -= minDbn;
+            }
+            //*
+            else if (node instanceof IRLetted) {
+                const max = getMaxVarDbn(node.value);
+                if (
+                // no vars
+                typeof max !== "number" ||
+                    // defined outside of letted
+                    max >= relativeDbn) {
+                    node.dbn -= minDbn;
+                }
+                else // if depends on vars in this letted
+                 {
+                    // TODO: fix double checking already inlined values
+                    //
+                    // this is currently a workaround
+                    //
+                    // the real problem is that sometimes (when?)
+                    // `iterTree` goes back checking some value that was already modified
+                    // in the case of `IRApp` as parent, throwing an error
+                    // because we don't know which value we should modify
+                    if (node.parent instanceof IRApp) {
+                        const parent = node.parent;
+                        const currentChild = node;
+                        if ( // parent is actually pointing to child
+                        currentChild === parent.arg ||
+                            currentChild === parent.fn ||
+                            equalIrHash(parent.arg.hash, currentChild.hash) ||
+                            equalIrHash(parent.fn.hash, currentChild.hash)) {
+                            // inline
+                            _modifyChildFromTo(node.parent, node, node.value);
+                            return true; // modified parent
+                        }
+                        else
+                            return false; // modified parent
+                    }
+                    else {
+                        if (node.parent) // only modify if not root
+                         {
+                            // inline
+                            _modifyChildFromTo(node.parent, node, node.value);
+                            return true; // modified parent
+                        }
+                        else
+                            return false;
+                    }
+                }
+            }
+            //*/
+        }, 
+        // shouldSkipNode ?
+        // hoisted terms are not really here
+        // will be substituted to variables when the time comes
+        // however now are here and we need to skip them
+        //
+        // !!! WARNING !! removing this causes strange uplc compilation BUGS
+        (node, dbn) => node instanceof IRHoisted);
+    // !!! IMPORTANT !!! _getMinUnboundDbn( value ) MUST be called on the original value; NOT the **modified** `normalized_value`
+    return [lettedDbn - (_getMinUnboundDbn(value) ?? minDbn), normalized_value];
+}
+/**
+ *
+ * @param term the ir term to iter to search for vars
+ * @returns {number | undefined}
+ *
+ * @example
+ * ```ts
+ * let minDbn = getMinVarDbn( new IRVar(0) ); // 0
+ * minDbn = getMinVarDbn( IRConst.unit ); // undefined
+ * minDbn = getMinVarDbn( new IRFunc( 1, new IRVar( 0 ) ) ); // 0
+ * ```
+ */
+export function getMinVarDbn(term) {
+    let min = undefined;
+    let foundAny = false;
+    iterTree(term, (node) => {
+        if (node instanceof IRVar ||
+            node instanceof IRSelfCall) {
+            if (foundAny) {
+                min = Math.min(min, node.dbn);
+            }
+            else {
+                foundAny = true;
+                min = node.dbn;
+            }
+        }
+    }, 
+    // shouldSkipNode ?
+    // hoisted terms are not really here
+    // will be substituted to variables when the time comes
+    // however now are here and we need to skip them
+    node => node instanceof IRHoisted // skip if hoisted
+    );
+    return min;
+}
+/**
+ *
+ * @param term the ir term to iter to search for vars
+ * @returns {number | undefined}
+ */
+function getMaxVarDbn(term) {
+    let max = undefined;
+    let foundAny = false;
+    iterTree(term, (node) => {
+        if (node instanceof IRVar ||
+            node instanceof IRSelfCall) {
+            if (foundAny) {
+                max = Math.max(max, node.dbn);
+            }
+            else {
+                foundAny = true;
+                max = node.dbn;
+            }
+        }
+    }, 
+    // shouldSkipNode ?
+    // hoisted terms are not really here
+    // will be substituted to variables when the time comes
+    // however now are here and we need to skip them
+    node => node instanceof IRHoisted // skip if hoisted
+    );
+    return max;
+}

package/dist/IR/IRNodes/IRNative/IRNativeTag.d.ts

@@ -0,0 +1,138 @@
+/**
+ * we use positive for natives which map to `UPLCBuiltin`
+ * possibly keeping the same number
+ *
+ * we use negatives for natives of the `std::fn` family
+ * since there is no negative `UPLCBuiltin` tag
+ */
+export declare enum IRNativeTag {
+    addInteger = 0,
+    subtractInteger = 1,
+    multiplyInteger = 2,
+    divideInteger = 3,
+    quotientInteger = 4,
+    remainderInteger = 5,
+    modInteger = 6,
+    equalsInteger = 7,
+    lessThanInteger = 8,
+    lessThanEqualInteger = 9,
+    appendByteString = 10,
+    consByteString = 11,
+    sliceByteString = 12,
+    lengthOfByteString = 13,
+    indexByteString = 14,
+    equalsByteString = 15,
+    lessThanByteString = 16,
+    lessThanEqualsByteString = 17,
+    sha2_256 = 18,
+    sha3_256 = 19,
+    blake2b_256 = 20,
+    verifyEd25519Signature = 21,
+    appendString = 22,
+    equalsString = 23,
+    encodeUtf8 = 24,
+    decodeUtf8 = 25,
+    strictIfThenElse = 26,
+    chooseUnit = 27,
+    trace = 28,
+    fstPair = 29,
+    sndPair = 30,
+    strictChooseList = 31,
+    mkCons = 32,
+    headList = 33,
+    tailList = 34,
+    nullList = 35,
+    chooseData = 36,
+    constrData = 37,
+    mapData = 38,
+    listData = 39,
+    iData = 40,
+    bData = 41,
+    unConstrData = 42,
+    unMapData = 43,
+    unListData = 44,
+    unIData = 45,
+    unBData = 46,
+    equalsData = 47,
+    mkPairData = 48,
+    mkNilData = 49,
+    mkNilPairData = 50,
+    serialiseData = 51,
+    verifyEcdsaSecp256k1Signature = 52,
+    verifySchnorrSecp256k1Signature = 53,
+    bls12_381_G1_add = 54,
+    bls12_381_G1_neg = 55,
+    bls12_381_G1_scalarMul = 56,
+    bls12_381_G1_equal = 57,
+    bls12_381_G1_hashToGroup = 58,
+    bls12_381_G1_compress = 59,
+    bls12_381_G1_uncompress = 60,
+    bls12_381_G2_add = 61,
+    bls12_381_G2_neg = 62,
+    bls12_381_G2_scalarMul = 63,
+    bls12_381_G2_equal = 64,
+    bls12_381_G2_hashToGroup = 65,
+    bls12_381_G2_compress = 66,
+    bls12_381_G2_uncompress = 67,
+    bls12_381_millerLoop = 68,
+    bls12_381_mulMlResult = 69,
+    bls12_381_finalVerify = 70,
+    keccak_256 = 71,
+    blake2b_224 = 72,
+    integerToByteString = 73,
+    byteStringToInteger = 74,
+    andByteString = 75,
+    orByteString = 76,
+    xorByteString = 77,
+    complementByteString = 78,
+    readBit = 79,
+    writeBits = 80,
+    replicateByte = 81,
+    shiftByteString = 82,
+    rotateByteString = 83,
+    countSetBits = 84,
+    findFirstSetBit = 85,
+    ripemd_160 = 86,
+    _dropList = -4,
+    _foldr = -6,
+    _foldl = -7,
+    _mkFindDataOptional = -8,
+    _length = -9,
+    _some = -10,
+    _every = -11,
+    _mkFilter = -12,
+    _id = -15,
+    _not = -16,
+    _strictAnd = -17,
+    _and = -18,
+    _strictOr = -19,
+    _or = -20,
+    _gtBS = -21,
+    _gtEqBS = -22,
+    _gtInt = -23,
+    _gtEqInt = -24,
+    _strToData = -25,
+    _pairDataToData = -26,
+    _strFromData = -27,
+    _pairDataFromData = -28,
+    _mkEqualsList = -31,
+    _equalPairData = -32,
+    /**
+     * function eqBool( a: boolean, b: boolean ): boolean
+     * {
+     *    return a ? ( b ? true : false ) : ( b ? false : true );
+     * }
+    **/
+    _equalBoolean = -33,
+    _negateInt = -34,
+    _mkMapList = -35,
+    _bytesToIntBE = -36,
+    _boolToInt = -37,
+    _intToBytesBE = -38,
+    _intToBool = -39,
+    _exponentiateInteger = -40,
+    _amountOfValue = -41,
+    _isZero = -42,
+    _sortedValueLovelaces = -43
+}
+export declare function nativeTagToString(nativeTag: IRNativeTag): string;