@guardian-network/shared 0.3.2

package/src/misc-utils/find-cycle-node.helper.ts

@@ -0,0 +1,53 @@
+import { DslNode, NodeWithReference } from '../types/dsl.types';
+
+export const findCycle = (nodes: DslNode[]): NodeWithReference | null => {
+  const nodeMap = new Map<string, DslNode>();
+  nodes.forEach((node) => nodeMap.set(node.id, node));
+
+  const visited = new Set<string>();
+  const explored = new Set<string>();
+
+  const hasCycle = (
+    nodeId: string,
+    parentNodeId: string,
+  ): [/* isCyclic:  */ boolean, NodeWithReference?] => {
+    if (visited.has(nodeId)) {
+      return [true, { nodeId, parentNodeId }];
+    }
+
+    if (explored.has(nodeId)) {
+      return [false];
+    }
+
+    const node = nodeMap.get(nodeId);
+    if (!node) {
+      throw new Error(
+        `Node ${nodeId} not found in graph. Probably nodeIds are hashed incorrectly.`,
+      );
+    }
+
+    visited.add(nodeId);
+
+    for (const referenceId of node.references) {
+      const recTest = hasCycle(referenceId, nodeId);
+
+      if (recTest[0]) {
+        return recTest;
+      }
+    }
+
+    visited.delete(nodeId);
+    explored.add(nodeId);
+
+    return [false];
+  };
+
+  for (const node of nodes) {
+    const cycleTestResult = hasCycle(node.id, '0');
+    if (!explored.has(node.id) && cycleTestResult[0]) {
+      return cycleTestResult[1]!;
+    }
+  }
+
+  return null;
+};

package/src/misc-utils/index.ts

@@ -0,0 +1,3 @@
+export * from './data-structure-transformation.helper';
+export * from './find-cycle-node.helper';
+export * from './node-id-tooling';

package/src/misc-utils/node-id-tooling.ts

@@ -0,0 +1,15 @@
+import { solidityPackedKeccak256 as keccak256Hash } from 'ethers';
+export { solidityPackedKeccak256 as keccak256Hash } from 'ethers';
+
+export class NodeId {
+  // note: this takes (intermeditate presentation of artifact + salt = node_id)
+  // with significant uniqueness level
+  static fromNotation(artifactIntermediateForm: string, salt: number): string {
+    // todo: validate 'artifactIntermediateForm' relying on Regex
+    const nodeId = keccak256Hash(
+      ['string', 'uint256'],
+      [artifactIntermediateForm.trim(), salt],
+    );
+    return nodeId;
+  }
+}

package/src/solidity-encode-decode/decode.helper.ts

@@ -0,0 +1,57 @@
+import { DecodedParamType } from '../types/solidity-decode.types';
+import { defaultAbiCoder } from './';
+
+type SolidityDecodeReturnType = ReturnType<typeof defaultAbiCoder.decode>;
+type SolidityDecodeInputParamsType = Parameters<typeof defaultAbiCoder.decode>;
+
+type PreciseDecodedParamType<T> = T extends 'string'
+  ? string
+  : T extends 'bool'
+    ? boolean
+    : T extends 'uint256'
+      ? bigint
+      : T extends 'bytes' // todo: add support of 'bytes32'
+        ? string
+        : any;
+
+export const solidityDecode = (
+  ...params: SolidityDecodeInputParamsType
+): SolidityDecodeReturnType => {
+  return defaultAbiCoder.decode(...params);
+};
+
+export const solidityDecodeSingleParam = <T extends DecodedParamType>(
+  type: T,
+  data: string,
+): PreciseDecodedParamType<T> => {
+  const decodedArray = solidityDecode([type], data).toArray();
+
+  if (decodedArray.length !== 1)
+    throw new Error(
+      'Decode: Solidity data contains more than single param value',
+    );
+  const [result] = decodedArray;
+
+  const resultWithPropperType = inferAndPopulateWithTypescriptType(
+    type,
+    result,
+  );
+  return resultWithPropperType;
+};
+
+const inferAndPopulateWithTypescriptType = <T extends DecodedParamType>(
+  type: T,
+  value: any,
+) => {
+  if (type === 'string') {
+    return value as PreciseDecodedParamType<T>;
+  } else if (type === 'bool') {
+    return value as PreciseDecodedParamType<T>;
+  } else if (type === 'uint256') {
+    return BigInt(value) as PreciseDecodedParamType<T>;
+  } else if (type === 'bytes') {
+    return value as PreciseDecodedParamType<T>;
+  }
+
+  throw new Error('Decode: Not supported decoding type');
+};

package/src/solidity-encode-decode/encode.helper.ts

@@ -0,0 +1,133 @@
+import {
+  SolidityAddressType,
+  SolidityBytesType,
+} from '../solidity-types/native-types';
+import {
+  EncodedParamType,
+  ObjectEncodeParamTypes,
+  PrimitiveEncodeParamTypes,
+} from '../types/solidity-encode.types';
+import { defaultAbiCoder } from './';
+
+type SolidityEncodeReturnType = ReturnType<typeof defaultAbiCoder.encode>;
+type SolidityEncodeInputParamsType = Parameters<typeof defaultAbiCoder.encode>;
+
+type PreciseEncodedParamType<T extends EncodedParamType> = T extends string
+  ? 'string'
+  : T extends boolean
+    ? 'bool'
+    : T extends number
+      ? 'uint256'
+      : T extends SolidityAddressType
+        ? 'address'
+        : T extends SolidityBytesType
+          ? 'bytes'
+          : /* : T extends SolidityUint24ListType
+            ? 'uint24[]' */
+            any;
+
+export const solidityEncode = (
+  ...params: SolidityEncodeInputParamsType
+): SolidityEncodeReturnType => {
+  return defaultAbiCoder.encode(...params);
+};
+
+// note: this encode string, number, bool into respective Solidity presentation; type will pick automatically
+// unless ObjectEncodeParamTypes is applied, this will fail with proper encoding when raw string-bytes or string-address supplied
+export const solidityEncodeSingleParam = <T extends EncodedParamType>(
+  primitiveTypeOrObject: T,
+): SolidityEncodeReturnType => {
+  const { typename, value: unpackedValue } = inferSolidityType(
+    primitiveTypeOrObject,
+  );
+
+  const encodedResult = solidityEncode([typename], [unpackedValue]);
+  return encodedResult;
+};
+
+export const solidityEncodeMultipleParams = <T extends Array<EncodedParamType>>(
+  ...primitiveTypeOrObjectList: T
+): SolidityEncodeReturnType => {
+  const typesAndValues = primitiveTypeOrObjectList.map((v) =>
+    inferSolidityType(v),
+  );
+
+  const encodedResult = solidityEncode(
+    typesAndValues.map((v) => v.typename),
+    typesAndValues.map((v) => v.value),
+  );
+  return encodedResult;
+};
+
+export const inferSolidityType = <T extends EncodedParamType>(
+  primitiveTypeOrObject: T,
+) => {
+  if (isPrimitiveType(primitiveTypeOrObject)) {
+    return inferPirimitiveType(primitiveTypeOrObject);
+  } else if (isObjectType(primitiveTypeOrObject)) {
+    return inferObjectType(primitiveTypeOrObject);
+  } else
+    throw new Error(
+      `Encode: Provide with not supported encoding type ${primitiveTypeOrObject}`,
+    );
+};
+
+const inferPirimitiveType = <T extends PrimitiveEncodeParamTypes>(
+  primitiveTypeOrObject: T,
+) => {
+  let typename: PreciseEncodedParamType<T>;
+  let value = primitiveTypeOrObject;
+
+  const type = typeof primitiveTypeOrObject;
+  if (type === 'boolean') {
+    typename = 'bool' as PreciseEncodedParamType<T>;
+  } else if (type === 'string') {
+    typename = 'string' as PreciseEncodedParamType<T>;
+  } else if (type === 'number') {
+    typename = 'uint256' as PreciseEncodedParamType<T>;
+  } else
+    throw new Error(
+      `Encode: Not supported encoding type for primitive-type ${type}`,
+    );
+
+  return { typename, value };
+};
+
+const inferObjectType = <T extends ObjectEncodeParamTypes>(
+  primitiveTypeOrObject: T,
+) => {
+  let typename: PreciseEncodedParamType<T>;
+  const value = primitiveTypeOrObject.value;
+
+  if (primitiveTypeOrObject instanceof SolidityAddressType) {
+    typename = 'address' as PreciseEncodedParamType<T>;
+  } else if (primitiveTypeOrObject instanceof SolidityBytesType) {
+    typename = 'bytes' as PreciseEncodedParamType<T>;
+  } /* else if (primitiveTypeOrObject instanceof SolidityUint24ListType) {
+    typename = 'uint24[]' as PreciseEncodedParamType<T>;
+  } */ else
+    throw new Error(
+      `Encode: Not supported encoding type for object: ${primitiveTypeOrObject}`,
+    );
+  return { typename, value };
+};
+
+// guards
+const isPrimitiveType = (
+  value: EncodedParamType,
+): value is PrimitiveEncodeParamTypes => {
+  const type = typeof value;
+  return type === 'string' || type === 'boolean' || type === 'number';
+};
+
+const isObjectType = (
+  value: EncodedParamType,
+): value is ObjectEncodeParamTypes => {
+  const type = typeof value;
+  return (
+    type === 'object' &&
+    (value instanceof SolidityAddressType ||
+      value instanceof SolidityBytesType) /* ||
+      value instanceof SolidityUint24ListType */
+  );
+};

package/src/solidity-encode-decode/index.ts

@@ -0,0 +1,10 @@
+import { AbiCoder } from 'ethers';
+export { solidityDecode, solidityDecodeSingleParam } from './decode.helper';
+export {
+  inferSolidityType,
+  solidityEncode,
+  solidityEncodeMultipleParams,
+  solidityEncodeSingleParam,
+} from './encode.helper';
+
+export const defaultAbiCoder = AbiCoder.defaultAbiCoder();

package/src/solidity-types/base/SolidityType.ts

@@ -0,0 +1,26 @@
+type Verifier<T> = (value: T) => T;
+
+export abstract class SolidityType<T> {
+  static build<T, R>(
+    this: new (param: T, verifierMethod: Verifier<T>) => R,
+    nonVerifiedValue: T,
+    verifier: Verifier<T>,
+  ): R {
+    const verified = verifier(nonVerifiedValue);
+
+    return new this(verified, verifier);
+  }
+
+  constructor(
+    protected verifiedValue: T,
+    protected verifierMethod: Verifier<T>,
+  ) {}
+
+  public get value(): T {
+    return this.verifiedValue;
+  }
+
+  protected setValue(value: T) {
+    this.verifiedValue = this.verifierMethod(value);
+  }
+}

package/src/solidity-types/base/index.ts

@@ -0,0 +1 @@
+export * from './SolidityType';

package/src/solidity-types/constants.ts

@@ -0,0 +1,23 @@
+export const SOLIDITY_UINT256 = 'uint256';
+export const SOLIDITY_BOOL = 'bool';
+export const SOLIDITY_ADDRESS = 'address';
+export const SOLIDITY_BYTES32 = 'bytes32'; // NOT SUPPORTED YET, but wraps into SOLIDITY_BYTES offchain
+
+export const SOLIDITY_BYTES = 'bytes';
+export const SOLIDITY_STRING = 'string';
+export const SOLIIDTY_UINT24_LIST = 'uint24[]'; // NOT SUPPORTED YET onchain, but wraps into SOLIDITY_BYTES offchain
+
+// todo: retrieve at compile-time from '../../contracts/pre-defined/constants/ValueTypeNames.sol'
+export const ALLOWED_SOLIDITY_VALUE_TYPES: Array<string> = [
+  SOLIDITY_UINT256,
+  SOLIDITY_BOOL,
+  SOLIDITY_ADDRESS,
+  // SOLIDITY_BYTES32,
+];
+
+// todo: retrieve at compile-time from '../../contracts/pre-defined/constants/ReferenceTypeNames.sol'
+export const ALLOWED_SOLIDITY_REFERENCE_TYPES: Array<string> = [
+  SOLIDITY_BYTES,
+  SOLIDITY_STRING,
+  SOLIIDTY_UINT24_LIST,
+];

package/src/solidity-types/index.ts

@@ -0,0 +1,4 @@
+export * from './constants';
+export * from './native-types';
+export * from './solidity-types-verification.helper';
+export * from './synthetic-types';

package/src/solidity-types/native-types/SolidityAddressType.ts

@@ -0,0 +1,13 @@
+import { SolidityType } from '../base';
+import { verifyAddress } from '../solidity-types-verification.helper';
+
+// natively supported type in artifacts
+export class SolidityAddressType extends SolidityType<string> {
+  static create = (address: string) => {
+    return this.build(address, verifyAddress);
+  };
+
+  public get address(): string {
+    return this.verifiedValue;
+  }
+}

package/src/solidity-types/native-types/SolidityBytesType.ts

@@ -0,0 +1,15 @@
+import { SolidityType } from '../base';
+import { verifyBytes } from '../solidity-types-verification.helper';
+
+// natively supported type in artifacts
+export class SolidityBytesType extends SolidityType<string> {
+  static create = (bytes: string) => {
+    return this.build(bytes, verifyBytes);
+  };
+
+  // 'SolidityBytesType' has to have at least one even private method that differs
+  // from 'SolidityAddressType'; otherwise 'PreciseEncodedParamType' won't work properly
+  public get bytes(): string {
+    return this.verifiedValue;
+  }
+}

package/src/solidity-types/native-types/index.ts

@@ -0,0 +1,2 @@
+export * from './SolidityAddressType';
+export * from './SolidityBytesType';

package/src/solidity-types/solidity-types-packing.helper.ts

@@ -0,0 +1,13 @@
+import { solidityEncode } from '../solidity-encode-decode';
+import { SOLIIDTY_UINT24_LIST } from './constants';
+import { verifyUint24Array } from './solidity-types-verification.helper';
+
+export const packAndVerifyUint24List = (list: number[]) => {
+  const verifiedList = verifyUint24Array(list);
+  const bytesPackedList = solidityEncode(
+    [SOLIIDTY_UINT24_LIST],
+    [verifiedList],
+  );
+
+  return bytesPackedList;
+};

package/src/solidity-types/solidity-types-verification.helper.ts

@@ -0,0 +1,52 @@
+import { getAddress, getBytes } from 'ethers';
+
+export const verifyAddress = (value: string) => {
+  // validates, normalizes and returns checksumed value
+  const address = getAddress(value);
+  return address;
+};
+
+export const verifyAddressesList = (list: Array<string>) => {
+  const verifiedList = list.map((v) => verifyAddress(v));
+
+  return verifiedList;
+};
+
+export const verifyBytesList = (list: Array<string>) => {
+  const verifiedList = list.map((v) => verifyBytes(v));
+
+  return verifiedList;
+};
+
+export const verifyBytes = (value: string) => {
+  // just a validation; no need to return as Uint8Array
+  getBytes(value);
+  return value;
+};
+
+export const verifyUint24Array = (
+  list: Array<number>,
+  expectedLength?: number,
+) => {
+  // validates each element fits into solidity uint24 type
+  const isValidTreshold = (value: number): boolean => {
+    const tresholdMin = 0;
+    const tresholdMax = Math.pow(2, 24);
+
+    const result = value >= tresholdMin && value <= tresholdMax;
+    return result;
+  };
+
+  let isValid =
+    Array.isArray(list) &&
+    list.every((value) => typeof value === 'number' && isValidTreshold(value));
+
+  // validate: 'list.length' is equal to 'expectedLength'
+  isValid = !!expectedLength
+    ? isValid && list.length === expectedLength
+    : isValid;
+
+  if (!isValid) throw new Error(`Can not satisfy Uint24 array validations`);
+
+  return list;
+};

package/src/solidity-types/synthetic-types/SolidityAddressListPacked.ts

@@ -0,0 +1,13 @@
+import { solidityEncode } from '../../solidity-encode-decode';
+import { SolidityBytesType } from '../native-types';
+import { verifyAddressesList } from '../solidity-types-verification.helper';
+
+// todo: refactor as done in 'SolidityUint24ListTypePacked'
+export class SolidityAddressListPacked extends SolidityBytesType {
+  static fromList = (list: Array<string>) => {
+    const verifiedList = verifyAddressesList(list);
+    const toBytes = solidityEncode(['address[]'], [verifiedList]);
+
+    return this.create(toBytes);
+  };
+}

package/src/solidity-types/synthetic-types/SolidityBytes32Packed.ts

@@ -0,0 +1,13 @@
+import { solidityEncode } from '../../solidity-encode-decode';
+import { SolidityBytesType } from '../native-types';
+import { verifyBytes } from '../solidity-types-verification.helper';
+
+// todo: refactor as done in 'SolidityUint24ListTypePacked'
+export class SolidityBytes32TypePacked extends SolidityBytesType {
+  static fromString = (bytes32Value: string) => {
+    verifyBytes(bytes32Value);
+    const toBytes = solidityEncode(['bytes32'], [bytes32Value]);
+
+    return this.create(toBytes);
+  };
+}

package/src/solidity-types/synthetic-types/SolidityBytesListPacked.ts

@@ -0,0 +1,13 @@
+import { solidityEncode } from '../../solidity-encode-decode';
+import { SolidityBytesType } from '../native-types';
+import { verifyBytesList } from '../solidity-types-verification.helper';
+
+// todo: refactor as done in 'SolidityUint24ListTypePacked'
+export class SolidityBytesListPacked extends SolidityBytesType {
+  static fromList = (list: Array<string>) => {
+    verifyBytesList(list);
+    const toBytes = solidityEncode(['bytes[]'], [list]);
+
+    return this.create(toBytes);
+  };
+}

package/src/solidity-types/synthetic-types/SolidityUint24ListTypePacked.ts

@@ -0,0 +1,31 @@
+import { solidityDecode } from '../../solidity-encode-decode';
+import { SOLIIDTY_UINT24_LIST } from '../constants';
+import { SolidityBytesType } from '../native-types';
+import { packAndVerifyUint24List } from '../solidity-types-packing.helper';
+import { verifyBytes } from '../solidity-types-verification.helper';
+
+export class SolidityUint24ListTypePacked extends SolidityBytesType {
+  static fromUint24List = (list: number[]) => {
+    const bytesPackedList = packAndVerifyUint24List(list);
+
+    return this.build(bytesPackedList, verifyBytes);
+  };
+
+  public get uintArray(): Array<bigint> {
+    const [decoded] = solidityDecode(
+      [SOLIIDTY_UINT24_LIST],
+      this.verifiedValue,
+    );
+    const result = [...(decoded as Array<bigint>)];
+    return result;
+  }
+
+  setValueAtPos = (pos: number, value: number) => {
+    const toNumbersList = this.uintArray.map((v) => Number(v)); // should be safe since it is in range of uint24
+    toNumbersList[pos] = value;
+
+    const bytesPackedList = packAndVerifyUint24List(toNumbersList);
+
+    this.setValue(bytesPackedList);
+  };
+}

package/src/solidity-types/synthetic-types/index.ts

@@ -0,0 +1,4 @@
+export * from './SolidityAddressListPacked';
+export * from './SolidityBytes32Packed';
+export * from './SolidityBytesListPacked';
+export * from './SolidityUint24ListTypePacked';

package/src/types/compiler.types.ts

@@ -0,0 +1,12 @@
+import { ContractRunner } from 'ethers';
+import { OnchainPresentation } from './contracts.types';
+
+export type ICompiler = {
+  compile(): Promise<OnchainPresentation>;
+};
+
+export interface LacLangCompilerOptions {
+  checkTypesAgainstOnchainDescriptors?: boolean;
+  checkTypesAgainstDslDeclarations?: boolean;
+  provider?: ContractRunner;
+}

package/src/types/contracts.types.ts

@@ -0,0 +1,58 @@
+// note: this file mostly duplicates types located in packages/contratcs/src/typechain/**
+import { AddressLike, BigNumberish, BytesLike } from 'ethers';
+
+type InjectionMetadataStruct = { value: string; index: BigNumberish };
+
+type SubstitutionArgumentStruct = {
+  supplierNodeId: BytesLike; // bytes32 encoded constant value
+  index: BigNumberish; // POSITION index in generic arguments list of particular node
+};
+
+type ConstantArgumentStruct = {
+  value: BytesLike; // bytes encoded constant value
+  index: BigNumberish; // POSITION index in generic arguments list of particular node
+};
+
+export type VariablesStruct = { nodeId: BytesLike; values: BytesLike[] };
+
+export type NodeInitDataStruct = {
+  id: BytesLike;
+  initData: BytesLike;
+  needsInitialization: boolean;
+  artifactAddress: AddressLike;
+  argsCount: BigNumberish;
+  constantExecArgs: ConstantArgumentStruct[];
+  substitutedExecArgs: SubstitutionArgumentStruct[];
+  variableExecArgs: BigNumberish[];
+  injections: InjectionMetadataStruct[];
+};
+
+type GraphInitParamsStruct = {
+  rootNode: BytesLike;
+  nodes: NodeInitDataStruct[];
+};
+
+export type OnchainPresentation = GraphInitParamsStruct;
+
+export type NodeTreeInitData = NodeInitDataStruct;
+
+// taken from 'packages/contracts/src/typechain/contracts/PolicyHandler.ts
+type ExecVarsMetadataStructOutputBase = {
+  nodeId: string;
+  nodeIndex: bigint;
+  artifactAddress: string;
+  descriptions: ArgumentDescriptionStructOutput[];
+  injections: StringAndIndexStructOutput[];
+};
+
+export type OnchainVariablesDescription = ExecVarsMetadataStructOutputBase;
+
+type ArgumentDescriptionStructOutput = {
+  name: string;
+  typename: string;
+};
+
+export type StringAndIndexStructOutput = {
+  value: string;
+  index: bigint;
+};

package/src/types/dsl.types.ts

@@ -0,0 +1,39 @@
+export type MinTypedValue = {
+  type: string;
+  value: string;
+};
+
+export interface DslNode {
+  id: string;
+  references: string[];
+}
+
+export type TypedValue = MinTypedValue & {
+  substitution?: boolean;
+  constant?: boolean;
+};
+
+export type InstanceConfigArgumentsOnly = {
+  execArguments: TypedValue[];
+  initArguments: TypedValue[];
+};
+
+export type InstanceConfigNameAndAddressOnly = {
+  name?: string;
+  artifactAddress: string;
+  needsInitialization: boolean;
+};
+
+export type InstanceConfig = InstanceConfigArgumentsOnly &
+  InstanceConfigNameAndAddressOnly;
+
+export type TranspilerOutput = {
+  ir: string;
+  rootNode: string;
+  typings: InstanceConfig[];
+};
+
+export type NodeWithReference = {
+  nodeId: string;
+  parentNodeId: string;
+};

package/src/types/index.ts

@@ -0,0 +1,6 @@
+export * from './compiler.types';
+export * from './contracts.types';
+export * from './dsl.types';
+export * from './intermediate-representation.types';
+export * from './solidity-decode.types';
+export * from './solidity-encode.types';

package/src/types/intermediate-representation.types.ts

@@ -0,0 +1,18 @@
+enum SupportedSolidityTypesEnum {
+  Uint256 = 'uint256',
+  String = 'string',
+  Bool = 'bool',
+  Bytes = 'bytes',
+  Address = 'address',
+}
+
+enum DSLTypesEnum {
+  Number = 'number',
+  String = 'string',
+  Bool = 'bool',
+  Bytes = 'bytes',
+  Address = 'address',
+}
+
+export type SupportedSolidityType = `${SupportedSolidityTypesEnum}`;
+export type DSLType = `${DSLTypesEnum}`;

package/src/types/solidity-decode.types.ts

@@ -0,0 +1,5 @@
+export type DecodedParamType =
+  | 'string'
+  | 'bool'
+  | 'uint256'
+  | 'bytes' /* | 'bytes32' */;