@guardian-network/policy-variables 0.3.2

package/src/insertion/Inserter.ts

@@ -0,0 +1,127 @@
+import { ErrorFactory } from '../errors';
+import {
+  AllowedVariablesType,
+  IAsyncMapGetter,
+  NodeId,
+  NodeVariablesConfig,
+  SuppliedVariables,
+  VarIndex,
+  VarName,
+  VarValue,
+} from '../types';
+
+// note: insert variable value
+export class Inserter implements IAsyncMapGetter<AllowedVariablesType> {
+  // static fromDump = (
+  //   varsConfig: NodeVariablesConfig[],
+  //   dump: SuppliedVariables[],
+  // ): Inserter => {
+  //   const inserter = new Inserter(varsConfig);
+  //   inserter.import(dump);
+  //   return inserter;
+  // };
+
+  // the node-with-no-variables list
+  private spareNodesConfig: NodeVariablesConfig[] = [];
+
+  // variable-unique-name => its-node-id
+  private varNameToNodeId: Map<VarName, NodeId> = new Map();
+
+  // variable-unique-name => its-index-in-node-vars-list (as defined in "this.nodeToVars")
+  private varNameToVarIndex: Map<VarName, VarIndex> = new Map();
+
+  // node-id => its-known-variables; known = filled
+  private nodeToVars: Map<NodeId, Array<VarValue>> = new Map();
+
+  constructor(
+    varsConfig /* expectedVarsConfig */ : NodeVariablesConfig[], // nodes-variables-config list
+  ) {
+    this.initialize(varsConfig);
+  }
+
+  private initialize = (varsConfig: NodeVariablesConfig[]) => {
+    for (const nodeVars of varsConfig) {
+      this.nodeToVars.set(nodeVars.nodeId, []);
+
+      // if (varsByNode.variables) { // note: legacy code has and ERROR at this point
+
+      if (nodeVars.variables.length === 0) {
+        this.spareNodesConfig.push(nodeVars);
+      } else {
+        for (const { index, uniqueName } of nodeVars.variables) {
+          this.varNameToNodeId.set(uniqueName, nodeVars.nodeId);
+          this.varNameToVarIndex.set(uniqueName, index);
+        }
+      }
+    }
+  };
+
+  insert = (varName: string, varValue: AllowedVariablesType) => {
+    const targetNodeId = this.varNameToNodeId.get(varName);
+    // won't reach if calling from Populator - getVarDescription will catch earlier
+    if (!targetNodeId) throw ErrorFactory.variableNodeNotFound(varName);
+
+    const nodeVariables = this.nodeToVars.get(targetNodeId);
+    // must have been caught in "initialized" previously
+    if (!nodeVariables)
+      throw ErrorFactory.nodeVariablesAreUndefined(targetNodeId);
+
+    nodeVariables.push({
+      // todo: safer approach
+      index: this.varNameToVarIndex.get(varName)!,
+      value: varValue,
+    });
+  };
+
+  get = (varName: string): AllowedVariablesType | undefined => {
+    const nodeId = this.varNameToNodeId.get(varName)!;
+
+    const result = this.nodeToVars
+      // todo: safer approach
+      .get(nodeId)!
+      .find((el) => el.index == this.varNameToVarIndex.get(varName))?.value;
+
+    return result;
+  };
+
+  import = (dump: Array<SuppliedVariables>) => {
+    for (const { nodeId, values } of dump) {
+      this.nodeToVars.set(
+        nodeId,
+        values.map((value, index) => ({ index, value })),
+      );
+    }
+  };
+
+  get filledVars(): SuppliedVariables[] {
+    const suppliedVars: SuppliedVariables[] = [];
+
+    for (let [targetNodeId, nodeVars] of this.nodeToVars) {
+      let filledVariable: SuppliedVariables = {} as SuppliedVariables;
+
+      const variableValuesTmp = new Array<AllowedVariablesType>(
+        nodeVars.length,
+      );
+
+      for (let { index, value } of nodeVars) {
+        // important: preserve index??; otherwise use nodeVars.map
+        variableValuesTmp[index] = value;
+      }
+
+      filledVariable.values = variableValuesTmp;
+      filledVariable.nodeId = targetNodeId;
+      suppliedVars.push(filledVariable);
+    }
+
+    const emptyVars: SuppliedVariables[] = this.spareNodesConfig.map(
+      ({ nodeId }) => ({
+        nodeId,
+        values: [],
+      }),
+    );
+
+    // note: also push nodes without variables so they are processed anyways
+    const result = [...suppliedVars, ...emptyVars];
+    return result;
+  }
+}

package/src/insertion/index.ts

@@ -0,0 +1 @@
+export { Inserter } from './Inserter';

package/src/types/index.ts

@@ -0,0 +1,2 @@
+export * from './interfaces';
+export * from './types';

package/src/types/interfaces.ts

@@ -0,0 +1,6 @@
+// export interface IAsyncMapGetter<ValueType> {
+export type SupportedTypes<T> = Promise<T> | T | undefined;
+
+export interface IAsyncMapGetter<T> {
+  get(key: string): SupportedTypes<T>;
+}

package/src/types/types.ts

@@ -0,0 +1,66 @@
+import {
+  OnchainVariablesDescription,
+  PrimitiveEncodeParamTypes,
+} from '@guardian-network/shared';
+
+/* type OnchainVariablesDescription = {
+  nodeId: string;
+  nodeIndex: bigint;
+  artifactAddress: string;
+  variables: ArgumentStructOutput[];
+  injections: StringAndIndexStructOutput[];
+}; */
+
+export type AllowedVariablesType = PrimitiveEncodeParamTypes; // string | number | boolean;
+
+// note: this reflects in some way a bit reshaped entry of 'NodeVariablesDescription' type
+export type VarDescription = {
+  name: string; // according to "Artifact.getExecDescriptor" definition, or dsl definition
+  type: string; // according to "Artifact.getExecDescriptor" definition, or dsl definition
+  uniqueName: string; // this contain unique variable name in comparison to other variables in the same node or in the other nodes
+  index: number; // position is node vars list
+  injection?: string; // unique injection-id if variable injects
+};
+
+export type VarValue = {
+  index: number;
+  value: AllowedVariablesType;
+};
+
+export type SuppliedVariables = {
+  nodeId: NodeId;
+  values: AllowedVariablesType[];
+};
+
+export type Variable = {
+  typename: string;
+  name: string;
+};
+
+type Injection = {
+  value: string;
+  index: number;
+};
+
+export type TypedRawOnchainVariablesDescription = {
+  nodeId: NodeId;
+  nodeIndex: number; // parent node
+  artifactAddress: string;
+  descriptions: Array<Variable>;
+  injections: Array<Injection>;
+};
+
+export type NodeVariablesDescription =
+  | OnchainVariablesDescription
+  | TypedRawOnchainVariablesDescription;
+
+// note: this reflects in some way a bit reshaped value of 'NodeVariablesDescription' type
+// see also, 'VarDescription' definition
+export type NodeVariablesConfig = {
+  nodeId: NodeId;
+  variables: VarDescription[];
+};
+
+export type VarName = string;
+export type VarIndex = number;
+export type NodeId = string;

package/src/utils/format-variables.helper.ts

@@ -0,0 +1,83 @@
+import { ErrorFactory } from '../errors';
+import {
+  NodeVariablesConfig,
+  NodeVariablesDescription,
+  TypedRawOnchainVariablesDescription,
+  Variable,
+} from '../types';
+
+export const translateVarsDescriptionToConfig = (
+  nodesVarsList: NodeVariablesDescription[],
+): NodeVariablesConfig[] => {
+  const nodesVarsConfig: NodeVariablesConfig[] = [];
+
+  for (let nodeVars of nodesVarsList.map(
+    rawOnchainVariablesDescriptionToOffchainView,
+  )) {
+    nodesVarsConfig.push({
+      nodeId: nodeVars.nodeId,
+      variables: [],
+    });
+
+    // note: add all variable data excluding injections
+    for (const [index, variable] of nodeVars.descriptions.entries()) {
+      const variableConfig = {
+        name: variable.name,
+        type: variable.typename,
+        uniqueName: buildUniqueVariablesName(variable, nodeVars),
+        index,
+      };
+
+      nodesVarsConfig[nodesVarsConfig.length - 1].variables.push(
+        variableConfig,
+      );
+    }
+
+    // note: add injections
+    for (const injection of nodeVars.injections) {
+      const injectableVar = nodesVarsConfig[
+        nodesVarsConfig.length - 1
+      ].variables.find((el) => el.index == Number(injection.index));
+
+      if (!!injectableVar) {
+        injectableVar.injection = injection.value;
+      } else
+        throw ErrorFactory.injectionFormatting(
+          injection.value,
+          injection.index,
+        );
+    }
+  }
+
+  return [...nodesVarsConfig];
+};
+
+export const rawOnchainVariablesDescriptionToOffchainView = (
+  nodeVars: NodeVariablesDescription,
+): TypedRawOnchainVariablesDescription => {
+  const { nodeId, descriptions, injections, artifactAddress, nodeIndex } =
+    nodeVars;
+
+  const result = {
+    nodeId,
+    nodeIndex: Number(nodeIndex),
+    artifactAddress,
+    descriptions: descriptions.map(({ typename, name }) => ({
+      typename,
+      name,
+    })),
+    injections: injections.map(({ value, index }) => ({
+      value,
+      index: Number(index),
+    })),
+  };
+  return result;
+};
+
+// note: this is a DEFINABLE method in what it outputs; double-check before applying adjustment
+const buildUniqueVariablesName = (
+  variable: Variable,
+  varDescription: NodeVariablesDescription,
+) => {
+  return `${variable.name}_${variable.typename}_${varDescription.artifactAddress}_${varDescription.nodeIndex}`;
+};

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export * from './format-variables.helper';
+export * from './validations.helper';

package/src/utils/validations.helper.ts

@@ -0,0 +1,116 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import {
+  SupportedSolidityType,
+  verifyAddress,
+  verifyBytes,
+} from '@guardian-network/shared';
+import { ErrorFactory } from '../errors';
+import {
+  AllowedVariablesType,
+  NodeVariablesConfig,
+  SuppliedVariables,
+  VarDescription,
+} from '../types';
+
+export const validateVarValueTypeWithErr = (
+  varValue: AllowedVariablesType,
+  expectedTypeAsString: string,
+) => {
+  const isValid = validateVarValueType(varValue, expectedTypeAsString);
+
+  if (!isValid) {
+    throw ErrorFactory.variableTypeNotMet(
+      varValue.toString(),
+      expectedTypeAsString,
+    );
+  }
+};
+
+// note: this validates that value complies with required solidity type
+const validateVarValueType = (
+  varValue: AllowedVariablesType,
+  expectedTypeString: string,
+  // todo: expectedTypeString: SupportedSolidityType
+): boolean => {
+  let verified = false;
+  // todo: apply safer approach instead assertion, since this gives no safe at this point
+  const vatiableSolidityType = expectedTypeString as SupportedSolidityType;
+
+  switch (vatiableSolidityType) {
+    // todo: case SupportedSolidityTypesEnum.String
+    case 'string':
+      verified ||= typeof varValue == 'string';
+      break;
+    case 'uint256':
+      verified ||= typeof varValue == 'number';
+      break;
+    case 'bool':
+      verified ||= typeof varValue == 'boolean';
+      break;
+    case 'address':
+      try {
+        verifyAddress(varValue as any as string);
+        verified = true;
+      } catch (_: unknown) {
+        verified = false;
+      }
+      break;
+    case 'bytes':
+      try {
+        verifyBytes(varValue as any as string);
+        verified = true;
+      } catch (_: unknown) {
+        verified = false;
+      }
+      break;
+    // note: handles when unknown (Solidty) type provided
+    default:
+      // should not reach there, since previous validations step in faster
+      throw ErrorFactory.providedVariableWithNotKnownType(
+        varValue.toString(),
+        vatiableSolidityType,
+      );
+  }
+
+  return verified;
+};
+
+const defaultExtraCondition = (_: VarDescription) => false;
+
+export const validateAllVariablesSupplied = (
+  varsConfig: NodeVariablesConfig[],
+  knownVariables: SuppliedVariables[],
+  // note: usually has to be "isInjection" func; when not, then instead default blank method consumed
+  isVariableInjectable: (
+    varDescription: VarDescription,
+  ) => boolean = defaultExtraCondition,
+) => {
+  for (let i = 0; i < varsConfig.length; i++) {
+    const suppliedVars = knownVariables[i];
+    const expectedVarsConfig = varsConfig[i];
+
+    for (let j = 0; j < expectedVarsConfig.variables.length; j++) {
+      const variable = expectedVarsConfig.variables[j];
+
+      // "defaultExtraCondition" gives "false" value, which treats each variable as NOT-AN-INJECTION
+      const isInjection = isVariableInjectable(variable);
+      const isVariableSupplied = suppliedVars.values[j] !== undefined;
+
+      // note: throw when not supplied and not injection
+      if (!isVariableSupplied && !isInjection) {
+        throw ErrorFactory.variableNotFilled(
+          variable.uniqueName,
+          variable.injection,
+        );
+      }
+
+      // note: this is intentional double validation of value type against the expected type
+      // the initial validation is done in VariablesPopulator.insert, or VariablesPopulator.inject
+      if (isVariableSupplied) {
+        const value = suppliedVars.values[j];
+        const expectedType = variable.type;
+        validateVarValueTypeWithErr(value, expectedType);
+      }
+    }
+  }
+};