Change implementation strategy of cashassembly, add scripts, comments support and tests

source/cash-assembly/primitive-evaluations.ts

@@ -64,15 +64,15 @@ type CallPrimitiveMethodParameters = {
 };
 
 /**
- * Inputs needed to resolve primitive method pushes from extracted CashAssembly identifiers.
+ * Inputs needed to resolve primitive method pushes from collected CashAssembly variable names.
  */
 export type ResolvePrimitiveMethodBytesParameters = {
 
     /**
-     * Variable identifiers from {@link extractVariablesFromEvaluations}, for example
+     * Variable names from {@link collectVariablesUsingParseScript}, for example
      * `['amount.toSatoshis', 'fee.toSatoshis']`.
      */
-    identifiers: string[];
+    variableNames: string[];
 
     /**
      * Variable names and values object.
@@ -101,7 +101,7 @@ const isResolvablePrimitiveType = (type: XOTemplatePrimitiveType | undefined): t
  *
  * @param {ResolvablePrimitiveType} type - Method resolvable template type.
  * @param {string} methodName - Method name from the evaluation text, for example `toSatoshis`.
- * @returns {boolean} True when that class exposes the named method.
+ * @returns {boolean} - True when that class exposes the named method.
  */
 const canResolvePrimitiveMethod = (type: ResolvablePrimitiveType, methodName: string): boolean => {
     const PrimitiveClass = RESOLVABLE_PRIMITIVE_CLASS_BY_TYPE[type];
@@ -159,7 +159,7 @@ const callPrimitiveMethod = (parameters: CallPrimitiveMethodParameters): unknown
  * @throws {@link CashAssemblyNumberNotSafeIntegerError} When a method return value is a number that is not a safe integer.
  */
 export const resolvePrimitiveMethodBytes = (parameters: ResolvePrimitiveMethodBytesParameters): Record<string, Uint8Array> => {
-    const { identifiers, templateVariables, variables } = parameters;
+    const { variableNames, templateVariables, variables } = parameters;
 
     // Without template metadata there is no type to select a primitive class.
     if (templateVariables === undefined) {
@@ -168,14 +168,14 @@ export const resolvePrimitiveMethodBytes = (parameters: ResolvePrimitiveMethodBy
 
     const resolvedBytes: Record<string, Uint8Array> = {};
 
-    for (const identifier of identifiers) {
-        // The same identifier can appear more than once. Resolve it only once.
-        if (Object.hasOwn(resolvedBytes, identifier) === true) {
+    for (const variableName of variableNames) {
+        // The same name can appear more than once. Resolve it only once.
+        if (Object.hasOwn(resolvedBytes, variableName) === true) {
             continue;
         }
 
-        // Find the primitive method reference in the identifier.
-        const methodReferenceMatch = identifier.match(CASHASSEMBLY_VARIABLE_METHOD_REFERENCE_PATTERN);
+        // Find the primitive method reference in the name.
+        const methodReferenceMatch = variableName.match(CASHASSEMBLY_VARIABLE_METHOD_REFERENCE_PATTERN);
 
         if (methodReferenceMatch === null) {
             continue;
@@ -183,7 +183,7 @@ export const resolvePrimitiveMethodBytes = (parameters: ResolvePrimitiveMethodBy
 
         const [ , baseName, methodName ] = methodReferenceMatch;
 
-        // Unknown identifiers and CashAssembly native operations such as someKey.schnorr_signature.all_outputs
+        // Unknown names and CashAssembly native operations such as someKey.schnorr_signature.all_outputs
         // must be left for CashAssembly rather than treated as primitive failures.
         if (Object.hasOwn(templateVariables, baseName) === false) {
             continue;
@@ -198,23 +198,23 @@ export const resolvePrimitiveMethodBytes = (parameters: ResolvePrimitiveMethodBy
 
         // Method resolvable type with an unknown method should throw.
         if (canResolvePrimitiveMethod(type, methodName) === false) {
-            throw new CashAssemblyPrimitiveMethodMissingError(identifier, methodName, type);
+            throw new CashAssemblyPrimitiveMethodMissingError(variableName, methodName, type);
         }
 
         // If the method is known but the runtime value is missing, throw an error.
         if (Object.hasOwn(variables, baseName) === false) {
-            throw new CashAssemblyPrimitiveVariableMissingError(identifier, baseName);
+            throw new CashAssemblyPrimitiveVariableMissingError(variableName, baseName);
         }
 
         const methodResult = callPrimitiveMethod({
-            identifier,
+            identifier: variableName,
             methodName,
             value: variables[baseName],
             type,
         });
 
-        // Store the result under identifier.
-        resolvedBytes[identifier] = convertValueToBytes(methodResult, identifier);
+        // CashAssembly looks up the full `base.method` name as WalletData bytes.
+        resolvedBytes[variableName] = convertValueToBytes(methodResult, variableName);
     }
 
     return resolvedBytes;