gen-typescript-from-tolk-dev 0.1.0 → 0.2.1

package/src/dynamic-get-methods.ts

@@ -1,454 +0,0 @@
-import * as c from '@ton/core';                 // todo is it peer dependency?
-import { DynamicCtx } from './dynamic-ctx';
-import { CantCallGetMethodDynamic, NotSupportedTypeOnStack } from './unsupported-errors'
-import { Ty } from './abi-types'
-import { createTonCoreDictionaryKey, createTonCoreDictionaryValue, dynamicPack, dynamicUnpack } from './dynamic-serialization'
-import { calcWidthOnStack, createLabelsForUnion, instantiateGenerics } from './types-kernel'
-import { checkIsArray, checkIsBoolean, checkIsNumber, checkIsObject, checkIsObjectWithProperty, throwInvalidInput } from './dynamic-validation'
-
-/*
-    Dynamic calling GET methods works without generating TypeScript wrappers.
-    Just given an ABI, pack any JS input to TVM stack (TupleItem[]), and unpack back.
-    Its purpose is orthogonal to wrappers:
-    - wrappers — for manual development
-                 (write tests, deployment, and other manual interactions with your contract)
-    - dynamic contract getters — for tolk-js, explorers, etc.
-                 (pass some data from auto-generated UI and invoke getters given its ABI)
- */
-
-type LoadCallback<T> = (s: c.Slice) => T
-
-export class StackReader {
-    constructor(private tuple: c.TupleItem[]) {
-    }
-
-    static fromGetMethod(expectedN: number, getMethodResult: { stack: c.TupleReader }): StackReader {
-        let tuple = [] as c.TupleItem[];
-        while (getMethodResult.stack.remaining) {
-            tuple.push(getMethodResult.stack.pop());
-        }
-        if (tuple.length !== expectedN) {
-            throw new Error(`expected ${expectedN} stack width, got ${tuple.length}`);
-        }
-        return new StackReader(tuple);
-    }
-
-    private popExpecting<ItemT>(itemType: string): ItemT {
-        const item = this.tuple.shift();
-        if (item?.type !== itemType) {
-            throw new Error(`not '${itemType}' on a stack`);
-        }
-        return item as ItemT;
-    }
-
-    readBigInt(): bigint {
-        return this.popExpecting<c.TupleItemInt>('int').value;
-    }
-
-    readBoolean(): boolean {
-        return this.popExpecting<c.TupleItemInt>('int').value !== 0n;
-    }
-
-    readCell(): c.Cell {
-        return this.popExpecting<c.TupleItemCell>('cell').cell;
-    }
-
-    readSlice(): c.Slice {
-        return this.popExpecting<c.TupleItemSlice>('slice').cell.beginParse();
-    }
-
-    readBuilder(): c.Builder {
-        return c.beginCell().storeSlice(this.popExpecting<c.TupleItemBuilder>('builder').cell.beginParse());
-    }
-
-    readUnknown(): c.TupleItem {
-        // `unknown` from Tolk is left as a raw tuple item
-        return this.tuple.shift()!;
-    }
-
-    readArrayOf<T>(readFn_T: (nestedReader: StackReader) => T): T[] {
-        const subItems = this.popExpecting<c.Tuple>('tuple').items;
-        const subReader = new StackReader(subItems);
-        // array len N => N subItems => N calls to readFn_T
-        return [...subItems].map(_ => readFn_T(subReader))
-    }
-
-    readLispListOf<T>(readFn_T: (nestedReader: StackReader) => T): T[] {
-        // read `[1 [2 [3 null]]]` to `[1 2 3]`
-        let pairReader: StackReader = this;
-        let outArr = [] as T[];
-        while (true) {
-            if (pairReader.tuple[0].type === 'null') {
-                pairReader.tuple.shift();
-                break;
-            }
-            let headAndTail = pairReader.popExpecting<c.Tuple>('tuple').items;
-            if (headAndTail.length !== 2) {
-                throw new Error(`malformed lisp_list, expected 2 stack width, got ${headAndTail.length}`);
-            }
-            pairReader = new StackReader(headAndTail);
-            outArr.push(readFn_T(pairReader));
-        }
-        return outArr;
-    }
-
-    readSnakeString(): string {
-        return this.readCell().beginParse().loadStringTail();
-    }
-
-    readTuple<T>(expectedN: number, readFn_T: (nestedReader: StackReader) => T): T {
-        const subItems = this.popExpecting<c.Tuple>('tuple').items;
-        if (subItems.length !== expectedN) {
-            throw new Error(`expected ${expectedN} items in a tuple, got ${subItems.length}`);
-        }
-        return readFn_T(new StackReader(subItems));
-    }
-
-    readNullLiteral(): null {
-        this.popExpecting<c.TupleItemNull>('null');
-        return null;
-    }
-
-    readNullable<T>(readFn_T: (r: StackReader) => T): T | null {
-        if (this.tuple[0].type === 'null') {
-            this.tuple.shift();
-            return null;
-        }
-        return readFn_T(this);
-    }
-
-    readWideNullable<T>(stackW: number, readFn_T: (r: StackReader) => T): T | null {
-        const slotTypeId = this.tuple[stackW - 1];
-        if (slotTypeId?.type !== 'int') {
-            throw new Error(`not 'int' on a stack`);
-        }
-        if (slotTypeId.value === 0n) {
-            this.tuple = this.tuple.slice(stackW);
-            return null;
-        }
-        const valueT = readFn_T(this);
-        this.tuple.shift();
-        return valueT;
-    }
-
-    readUnionType<T>(stackW: number, infoForTypeId: Record<number, [number, string | null, (r: StackReader) => any]>): T {
-        const slotTypeId = this.tuple[stackW - 1];
-        if (slotTypeId?.type !== 'int') {
-            throw new Error(`not 'int' on a stack`);
-        }
-        const info = infoForTypeId[Number(slotTypeId.value)];   // [stackWidth, label, readFn_T{i}]
-        if (info == null) {
-            throw new Error(`unexpected UTag=${slotTypeId.value}`);
-        }
-        const label = info[1];
-        this.tuple = this.tuple.slice(stackW - 1 - info[0]);
-        const valueT = info[2](this);
-        this.tuple.shift();
-        return label == null ? valueT : { $: label, value: valueT } as T;
-    }
-
-    readCellRef<T>(loadFn_T: LoadCallback<T>): { ref: T } {
-        return { ref: loadFn_T(this.readCell().beginParse()) };
-    }
-
-    readDictionary<K extends c.DictionaryKeyTypes, V>(keySerializer: c.DictionaryKey<K>, valueSerializer: c.DictionaryValue<V>): c.Dictionary<K, V> {
-        if (this.tuple[0].type === 'null') {
-            this.tuple.shift();
-            return c.Dictionary.empty<K, V>(keySerializer, valueSerializer);
-        }
-        return c.Dictionary.loadDirect<K, V>(keySerializer, valueSerializer, this.readCell());
-    }
-}
-
-// When constructing a TVM tuple (when calling a get method), we often need to make cells.
-// For example, given an address, we should result in { type: 'slice', cell: (serialized address) }
-function makeCell(ctx: DynamicCtx, fieldPath: string, ty: Ty, v: any): c.Cell {
-    let b = c.beginCell();
-    dynamicPack(ctx, fieldPath, ty, v, b);      // does validation, throws if invalid, e.g. number instead of address
-    return b.endCell();
-}
-
-// Pack value `v` of type `ty` to a TVM tuple, as an argument of a get method.
-// Parameter `fieldPath` is used for error messages only, e.g. when provided invalid input.
-function dynamicConstruct(ctx: DynamicCtx, fieldPath: string, ty: Ty, v: any, tupleIfW: boolean = false): c.TupleItem[] {
-    if (tupleIfW) {       // inside `array<T>` or `[T, ...]`, if T is non-primitive, it's a sub-tuple
-        if (calcWidthOnStack(ctx.symbols, ty) === 1) {
-            return dynamicConstruct(ctx, fieldPath, ty, v, false);
-        }
-        return [{ type: 'tuple', items: dynamicConstruct(ctx, fieldPath, ty, v, false) }];
-    }
-
-    switch (ty.kind) {
-        case 'int':
-        case 'intN':
-        case 'uintN':
-        case 'varintN':
-        case 'varuintN':
-        case 'coins': {
-            checkIsNumber(fieldPath, ty, v);
-            return [{ type: 'int', value: v }];
-        }
-        case 'bool': {
-            checkIsBoolean(fieldPath, ty, v);
-            return [{ type: 'int', value: (v ? -1n : 0n) }];
-        }
-        case 'cell': {
-            checkIsObject(fieldPath, ty, v);
-            return [{ type: 'cell', cell: v }];
-        }
-        case 'builder': {
-            // the call to `makeCell()`, automatically does validation of input (of v)
-            return [{ type: 'builder', cell: makeCell(ctx, fieldPath, ty, v) }];
-        }
-        case 'slice':
-        case 'remaining':
-        case 'address':
-        case 'addressExt':
-        case 'addressAny':
-        case 'bitsN': {
-            return [{ type: 'slice', cell: makeCell(ctx, fieldPath, ty, v) }];
-        }
-        case 'string': {
-            return [{ type: 'cell', cell: makeCell(ctx, fieldPath, ty, v) }];
-        }
-        case 'addressOpt': {
-            if (v === null) {
-                return [{ type: 'null' }];
-            }
-            return [{ type: 'slice', cell: makeCell(ctx, fieldPath, ty, v) }];
-        }
-        case 'nullLiteral': {
-            return [{ type: 'null' }];
-        }
-        case 'callable': {
-            throw new NotSupportedTypeOnStack(ty, fieldPath);
-        }
-        case 'void': {
-            return []
-        }
-        case 'unknown': {
-            checkIsObjectWithProperty(fieldPath, ty, v, 'type');    // c.TupleItem has 'type'
-            return [v as c.TupleItem];
-        }
-        case 'nullable': {
-            if (ty.stackTypeId) {
-                let result = [] as c.TupleItem[];
-                if (v === null) {
-                    for (let i = 0; i < ty.stackWidth! - 1; ++i) {
-                        result.push({ type: 'null' });
-                    }
-                    result.push({ type: 'int', value: 0n });
-                } else {
-                    result = dynamicConstruct(ctx, fieldPath, ty.inner, v);
-                    result.push({ type: 'int', value: BigInt(ty.stackTypeId) });
-                }
-                return result;
-            }
-            if (v === null) {
-                return [{ type: 'null' }];
-            }
-            return dynamicConstruct(ctx, fieldPath, ty.inner, v);
-        }
-        case 'cellOf': {
-            checkIsObjectWithProperty(fieldPath, ty, v, 'ref');
-            return [{ type: 'cell', cell: makeCell(ctx, fieldPath, ty.inner, v.ref) }];
-        }
-        case 'arrayOf': {
-            checkIsArray(fieldPath, ty, v);
-            return [{ type: 'tuple', items: v.map((ith: any) => dynamicConstruct(ctx, 'ith', ty.inner, ith, true)[0]) }];
-        }
-        case 'lispListOf': {
-            checkIsArray(fieldPath, ty, v);
-            return [v.reduceRight((tail: c.TupleItem, head: any) => (
-                { type: 'tuple', items: [dynamicConstruct(ctx, 'head', ty.inner, head, true)[0], tail] }
-            ), { type: 'null' })];
-        }
-        case 'tensor': {
-            checkIsArray(fieldPath, ty, v, ty.items.length);
-            return v.flatMap((item: any, idx: number) => dynamicConstruct(ctx, `${fieldPath}[${idx}]`, ty.items[idx], item));
-        }
-        case 'shapedTuple': {
-            checkIsArray(fieldPath, ty, v, ty.items.length);
-            return [{ type: 'tuple', items: v.map((ith: any, idx: number) => dynamicConstruct(ctx, `${fieldPath}[${idx}]`, ty.items[idx], ith, true)[0]) }];
-        }
-        case 'mapKV': {
-            checkIsObject(fieldPath, ty, v);
-            if (v.size === 0) {
-                return [{ type: 'null' }];
-            }
-            let dictKey = createTonCoreDictionaryKey(fieldPath, ty.k);
-            let dictValue = createTonCoreDictionaryValue(ctx, fieldPath, ty.v);
-            return [{ type: 'cell', cell: c.beginCell().storeDictDirect(v, dictKey, dictValue).endCell() }];
-        }
-        case 'EnumRef': {
-            checkIsNumber(fieldPath, ty, v);
-            return [{ type: 'int', value: v }];
-        }
-        case 'StructRef': {
-            checkIsObject(fieldPath, ty, v);
-            let structRef = ctx.symbols.getStruct(ty.structName);
-            return structRef.fields.flatMap(f => {
-                const fTy = ty.typeArgs ? instantiateGenerics(f.ty, structRef.typeParams, ty.typeArgs) : f.ty;
-                return dynamicConstruct(ctx, `${fieldPath}.${f.name}`, fTy, v[f.name]);
-            });
-        }
-        case 'AliasRef': {
-            let aliasRef = ctx.symbols.getAlias(ty.aliasName);
-            const targetTy = ty.typeArgs ? instantiateGenerics(aliasRef.targetTy, aliasRef.typeParams, ty.typeArgs) : aliasRef.targetTy;
-            return dynamicConstruct(ctx, fieldPath, targetTy, v);
-        }
-        case 'union': {
-            const variants = createLabelsForUnion(ctx.symbols, ty.variants);
-            const hasNull = variants.find(v => v.variantTy.kind === 'nullLiteral');
-            let result = [] as c.TupleItem[];
-            if (hasNull && v === null) {
-                for (let i = 0; i < ty.stackWidth - 1; ++i) {
-                    result.push({ type: 'null' });
-                }
-                result.push({ type: 'int', value: 0n });
-            } else {
-                checkIsObjectWithProperty(fieldPath, ty, v, '$');
-
-                const activeVariant = variants.find(variant => v.$ === variant.labelStr);
-                if (!activeVariant) {
-                    throwInvalidInput(fieldPath, ty, `non-existing union variant for $ = '${v.$}'`);
-                }
-                if (activeVariant.hasValueField && !v.hasOwnProperty('value')) {
-                    throwInvalidInput(fieldPath, ty, `expected {$,value} but field 'value' not provided`);
-                }
-                for (let i = 0; i < ty.stackWidth - 1 - activeVariant.stackWidth; ++i) {
-                    result.push({ type: 'null' });
-                }
-                let actualValue = activeVariant.hasValueField ? v.value : v;
-                result.push(...dynamicConstruct(ctx, `${fieldPath}#${activeVariant.labelStr}`, activeVariant.variantTy, actualValue));
-                result.push({ type: 'int', value: BigInt(activeVariant.stackTypeId) });
-            }
-            return result;
-        }
-        case 'genericT': throw new Error(`unexpected genericT=${ty.nameT} at ${fieldPath}`);
-    }
-}
-
-// Parse `ty` from a TVM tuple on a stack, returned as a result of a get method invocation.
-// Parameter `fieldPath` is used for error messages only, e.g. when can't deserialize CellRef<T>.
-function dynamicParse(ctx: DynamicCtx, r: StackReader, fieldPath: string, ty: Ty, unTupleIfW = false): any {
-    if (unTupleIfW) {       // inside `array<T>` or `[T, ...]`, if T is non-primitive, it's a sub-tuple
-        let wOnStack = calcWidthOnStack(ctx.symbols, ty);
-        if (wOnStack !== 1) {
-            return r.readTuple(wOnStack, (r) => dynamicParse(ctx, r, fieldPath, ty, false));
-        }
-    }
-
-    switch (ty.kind) {
-        case 'int':
-        case 'intN':
-        case 'uintN':
-        case 'varintN':
-        case 'varuintN':
-        case 'coins':       return r.readBigInt();
-        case 'bool':        return r.readBoolean();
-        case 'cell':        return r.readCell();
-        case 'builder':     return r.readBuilder();
-        case 'slice':       return r.readSlice();
-        case 'string':      return r.readSnakeString();
-        case 'remaining':   return r.readSlice();
-        case 'address':     return r.readSlice().loadAddress();
-        case 'addressOpt':  return dynamicParse(ctx, r, fieldPath, { kind: 'nullable', inner: { kind: 'address' } });
-        case 'addressExt':  return r.readSlice().loadExternalAddress();
-        case 'addressAny':  return dynamicUnpack(ctx, fieldPath, ty, r.readSlice());
-        case 'bitsN':       return r.readSlice();
-        case 'nullLiteral': return r.readNullLiteral();
-        case 'callable':    throw new NotSupportedTypeOnStack(ty, fieldPath);
-        case 'void':        return void 0;
-        case 'unknown':     return r.readUnknown();
-        case 'nullable': {
-            if (ty.stackTypeId) {
-                return r.readWideNullable(ty.stackWidth!, (r) => dynamicParse(ctx, r, fieldPath, ty.inner));
-            }
-            return r.readNullable((r) => dynamicParse(ctx, r, fieldPath, ty.inner));
-        }
-        case 'cellOf':      return r.readCellRef((s) => dynamicUnpack(ctx, fieldPath, ty.inner, s));
-        case 'arrayOf':     return r.readArrayOf((r) => dynamicParse(ctx, r, fieldPath, ty.inner, true));
-        case 'lispListOf':  return r.readLispListOf((r) => dynamicParse(ctx, r, fieldPath, ty.inner, true));
-        case 'tensor': {
-            let result = [];
-            for (let i = 0; i < ty.items.length; ++i) {
-                result.push(dynamicParse(ctx, r, `${fieldPath}[${i}]`, ty.items[i]));
-            }
-            return result;
-        }
-        case 'shapedTuple': {
-            return r.readTuple(ty.items.length, (r) => {
-                let result = [];
-                for (let i = 0; i < ty.items.length; ++i) {
-                    result.push(dynamicParse(ctx, r, `${fieldPath}[${i}]`, ty.items[i], true));
-                }
-                return result;
-            });
-        }
-        case 'mapKV': {
-            let dictKey = createTonCoreDictionaryKey(fieldPath, ty.k);
-            let dictValue = createTonCoreDictionaryValue(ctx, fieldPath, ty.v);
-            return r.readDictionary(dictKey, dictValue);
-        }
-        case 'EnumRef':     return r.readBigInt();
-        case 'StructRef': {
-            const structRef = ctx.symbols.getStruct(ty.structName);
-            let result = { $: ty.structName } as Record<string, any>;
-            for (let f of structRef.fields) {
-                const fTy = ty.typeArgs ? instantiateGenerics(f.ty, structRef.typeParams, ty.typeArgs) : f.ty;
-                result[f.name] = dynamicParse(ctx, r, `${fieldPath}.${f.name}`, fTy);
-            }
-            return result;
-        }
-        case 'AliasRef': {
-            const aliasRef = ctx.symbols.getAlias(ty.aliasName);
-            const targetTy = ty.typeArgs ? instantiateGenerics(aliasRef.targetTy, aliasRef.typeParams, ty.typeArgs) : aliasRef.targetTy;
-            return dynamicParse(ctx, r, fieldPath, targetTy);
-        }
-        case 'genericT':    throw new Error(`unexpected genericT=${ty.nameT} at ${fieldPath}`);
-        case 'union': {
-            const variants = createLabelsForUnion(ctx.symbols, ty.variants);
-            const infoForTypeId = {} as Record<number, [number, string | null, (r: StackReader) => any]>;
-            for (let v of variants) {
-                infoForTypeId[v.stackTypeId] = [v.stackWidth, v.hasValueField ? v.labelStr : null,
-                    (r: StackReader) => dynamicParse(ctx, r, `${fieldPath}#${v.labelStr}`, v.variantTy)
-                ];
-            }
-            return r.readUnionType(ty.stackWidth, infoForTypeId);
-        }
-    }
-}
-
-
-/**
- * Pack any `value` of type `ty` to a TVM tuple.
- * This tuple can be used as a get method argument or debug-printed as human-readable.
- */
-export function makeTvmTupleDynamic(ctx: DynamicCtx, ty: Ty, value: any): c.TupleItem[] {
-    return dynamicConstruct(ctx, 'value', ty, value);
-}
-
-/**
- * Invoke any get method taking plain JS variables as arguments and interpreting the resulting TVM tuple according to ABI.
- * Example: `get fun intAndPoint(i: int, p: Point): Point`.
- * Call: `callGetMethodDynamic(provider, ctx, 'intAndPoint', [num, {x: num, y: num}])` returns `{x: num, y: num}`.
- * When input is incorrect (e.g. missing property in a JS object), throws InvalidDynamicInput.
- */
-export async function callGetMethodDynamic(provider: c.ContractProvider, ctx: DynamicCtx, getMethodName: string, args: any[]): Promise<any> {
-    const getM = ctx.findGetMethod(getMethodName);
-    if (getM == null) {
-        throw new CantCallGetMethodDynamic(getMethodName, `method not found in contract ${ctx.contractName}`);
-    }
-    if (getM.parameters.length !== args.length) {      // default parameters not supported, dynamic invocation should provide all
-        throw new CantCallGetMethodDynamic(getMethodName, `expected ${getM.parameters.length} arguments, got ${args.length}`);
-    }
-
-    const stackIn: c.TupleItem[] = [];
-    for (let i = 0; i < args.length; ++i) {
-        stackIn.push(...dynamicConstruct(ctx, getM.parameters[i].name, getM.parameters[i].ty, args[i]));
-    }
-    const expectedSlotsOut = calcWidthOnStack(ctx.symbols, getM.returnTy);
-    const r = StackReader.fromGetMethod(expectedSlotsOut, await provider.get(getMethodName, stackIn));
-    return dynamicParse(ctx, r, 'result', getM.returnTy);
-}