Type hint support

solarkraft/src/fetch.ts

@@ -9,13 +9,47 @@
  * Igor Konnov, 2024
  */
 
+/**
+ * The fetch command optionally accepts a --typemap argument, which should be a .json file with the following structure:
+ *  {
+ *   "methods":{
+ *       "m1": [[T1_1, ..., T1_N1], R1],
+ *        ...
+ *       "mK": [[TK_1, ..., TK_NK], RK],
+ *      },
+ *   "variables": {
+ *       "v1": T1
+ *       ...
+ *       "vM": TM
+ *      }
+ *  }
+ *
+ * Where `mi` keys are the names of the methods, `vi` keys the names of variables,
+ * `Ti_j` is the type of the `j`-th argument to method `mi`,
+ * `Ri` is the return type of method `mi`,
+ *  and `Ti` is the type of the variable `vi`.
+ *
+ * Type syntax uses the following constructors:
+ *  - { "vec": elemT } for Vec - typed values
+ *  - { "map": [domT, cdmT]} for Map - typed values
+ *  - { a1: T1, ..., an: Tn } for Struct - typed values
+ *  - { "enum": [T1, ..., Tn]} for enums
+ * other literal types (e.g. Int) aren't required so they can be any string (which will be ignored).
+ *
+ * Note that typemap types are used as hints, and as such are redundant for any method/variable where the type is unambiguous
+ * from the transaction data json structure.
+ * Concretely, type hints are only _necessary_ when dealing with nullary Enum values, or Enum values indexed by Symbols/Strings, since
+ * those values are indistinguishable from vectors at the transaction data layer.
+ */
+
 import { Horizon } from '@stellar/stellar-sdk'
 import { extractContractCall } from './fetcher/callDecoder.js'
 import {
     loadFetcherState,
     saveContractCallEntry,
     saveFetcherState,
 } from './fetcher/storage.js'
+import { existsSync, readFileSync } from 'node:fs'
 
 // how often to query for the latest synchronized height
 const HEIGHT_FETCHING_PERIOD = 100
@@ -25,6 +59,14 @@ const HEIGHT_FETCHING_PERIOD = 100
  * @param args the arguments parsed by yargs
  */
 export async function fetch(args: any) {
+    const typemap = args.typemap
+
+    if (typemap !== undefined && !existsSync(typemap)) {
+        console.log(`The typemap file ${typemap} does not exist.`)
+        console.log('[Error]')
+        return
+    }
+
     const server = new Horizon.Server(args.rpc)
 
     const contractId = args.id
@@ -43,6 +85,10 @@ export async function fetch(args: any) {
         lastHeight = args.height
     }
 
+    const typemapJson = existsSync(typemap)
+        ? JSON.parse(readFileSync(typemap, 'utf8'))
+        : ({} as JSON)
+
     console.log(`Fetching fresh transactions from: ${args.rpc}...`)
 
     console.log(`Fetching the ledger for ${lastHeight}`)
@@ -73,7 +119,8 @@ export async function fetch(args: any) {
                 if (msg.transaction_successful) {
                     const callEntryMaybe = await extractContractCall(
                         msg,
-                        (id) => contractId === id
+                        (id) => contractId === id,
+                        typemapJson
                     )
                     if (callEntryMaybe.isJust()) {
                         const entry = callEntryMaybe.value

solarkraft/src/fetcher/callDecoder.ts

@@ -21,7 +21,8 @@ import { OrderedMap } from 'immutable'
  */
 export async function extractContractCall(
     op: any,
-    matcher: (contractId: string) => boolean
+    matcher: (contractId: string) => boolean,
+    typemapJson: any = {}
 ): Promise<Maybe<ContractCallEntry>> {
     // https://developers.stellar.org/network/horizon/api-reference/resources/operations/object/invoke-host-function
     if (op.function !== 'HostFunctionTypeHostFunctionTypeInvokeContract') {
@@ -58,6 +59,15 @@ export async function extractContractCall(
     const method = params[1]
     const methodArgs = params.slice(2)
 
+    // Now we look into the typemap file, to see if we're given type hints. This is effectively required
+    // for vector-like arguments, which could be encodings of enums:
+    // https://developers.stellar.org/docs/learn/smart-contract-internals/types/custom-types#enum-unit-and-tuple-variants
+    // Could be undefined, in which case we should fail on ambiguous input
+    const typeHints = {
+        methods: typemapJson['methods'] ?? {},
+        variables: typemapJson['variables'] ?? {},
+    }
+
     const tx = await op.transaction()
     // Get the containing ledger number:
     // https://developers.stellar.org/network/horizon/api-reference/resources/transactions/object
@@ -116,6 +126,7 @@ export async function extractContractCall(
         returnValue,
         fields,
         oldFields,
+        typeHints,
     })
 }
 

solarkraft/src/fetcher/storage.ts

@@ -82,6 +82,11 @@ export interface ContractCallEntry {
      * Flag which tracks whether this particular entry has already been verified, and, if it has been, the verification result.
      */
     verificationStatus?: VerificationStatus
+
+    /**
+     * Type hints for enum/vector disambiguation, if present.
+     */
+    typeHints?: any
 }
 
 /**
@@ -156,6 +161,7 @@ export function loadContractCallEntry(filename: string): ContractCallEntry {
         fields: OrderedMap<string, any>(loaded.fields),
         oldFields: OrderedMap<string, any>(loaded.oldFields),
         verificationStatus: loaded.verificationStatus ?? 'unverified',
+        typeHints: loaded.typeHints ?? {},
     }
 }
 

solarkraft/src/instrument.ts

@@ -106,6 +106,12 @@ export function instrumentMonitor(
         (k) => !contractCall.fields.has(k)
     )
 
+    const typeHints = contractCall.typeHints ?? {
+        methods: {},
+        variables: {},
+    }
+    const varHints = typeHints['variables'] ?? {}
+
     // TODO(#61): handle failed transactions
     // Add a special variable `last_error` that tracks error messages of failed transactions
     // fieldsToInstrument.push({ name: 'last_error', type: 'TlaStr', value: '' })
@@ -114,7 +120,11 @@ export function instrumentMonitor(
     const oldInstrumented = tlaJsonAnd(
         oldFieldsToInstrument
             .map((value, name) =>
-                tlaJsonEq__NameEx__ValEx(name, false, tlaJsonOfNative(value))
+                tlaJsonEq__NameEx__ValEx(
+                    name,
+                    false,
+                    tlaJsonOfNative(value, false, varHints[name])
+                )
             )
             .valueSeq()
             .toArray()
@@ -140,7 +150,7 @@ export function instrumentMonitor(
                 tlaJsonEq__NameEx__ValEx(
                     name,
                     true, // prime `name`
-                    tlaJsonOfNative(value)
+                    tlaJsonOfNative(value, false, varHints[name])
                 )
             )
             .valueSeq()
@@ -150,8 +160,12 @@ export function instrumentMonitor(
         missingFields.map((name) => tlaJsonEq__NameEx__ValEx(name, true, GEN1)) // name' = Gen(1)
     )
 
-    const tlaMethodArgs = contractCall.methodArgs.map((arg) =>
-        tlaJsonOfNative(arg)
+    const methodArgHints = ((typeHints['methods'] ?? {})[
+        contractCall.method
+    ] ?? [Array(contractCall.methodArgs.length).fill(undefined)])[0]
+
+    const tlaMethodArgs = contractCall.methodArgs.map((arg, i) =>
+        tlaJsonOfNative(arg, false, methodArgHints[i])
     )
     const tlaNext = tlaJsonOperDecl__And('Next', [
         tlaJsonApplication(
@@ -228,24 +242,50 @@ export function isTlaName(name: string): boolean {
  *   { "a": 3, "b": 5 }  ~~>  [ a |-> 3, b |-> 5 ]
  *   { "2": 3, "4": 5 }  ~~>  SetAsFun({ <<"2", 3>>, <<"4", 5>> })
  */
-export function tlaJsonOfNative(v: any, forceVec: boolean = false): any {
+export function tlaJsonOfNative(
+    v: any,
+    forceVec: boolean = false,
+    hint?: any
+): any {
     if (typeof v === 'object') {
         if (Array.isArray(v)) {
             // a JS array
+            // we require a hint in the case of ambiguous inputs
+            const mustHaveHint =
+                !forceVec &&
+                v.length > 0 &&
+                v.every((elem) => typeof elem === 'string')
+
+            if (mustHaveHint && hint === undefined)
+                throw new TypeError(
+                    `Ambiguous type detected for ${v}. Please \`fetch\` with --typemap provided.`
+                )
+
             if (
                 v.length == 0 ||
                 forceVec ||
-                v.every((elem) => typeof elem === typeof v[0])
+                (!mustHaveHint &&
+                    v.every((elem) => typeof elem === typeof v[0])) ||
+                (mustHaveHint && 'vec' in hint)
             ) {
                 // a Soroban `Vec`
                 // [ 1, 2, 3 ]  ~~>  << 1, 2, 3 >>
+                const childHints: any[] = Array(v.length).fill(
+                    (hint ?? {})['vec']
+                )
                 return {
                     type: 'Untyped',
                     kind: 'OperEx',
                     oper: 'TUPLE',
-                    args: v.map((arg) => tlaJsonOfNative(arg)),
+                    args: v.map((arg, i) =>
+                        tlaJsonOfNative(arg, forceVec, childHints[i])
+                    ),
                 }
-            } else if (v.length > 0 && typeof v[0] === 'string') {
+            } else if (
+                v.length > 0 &&
+                typeof v[0] === 'string' &&
+                (!mustHaveHint || 'enum' in hint)
+            ) {
                 // a Soroban `enum`
                 // [ 'A', 42 ]   ~~>  Variant("A", 42)
                 const tlaUnit = {
@@ -254,14 +294,22 @@ export function tlaJsonOfNative(v: any, forceVec: boolean = false): any {
                     oper: 'OPER_APP',
                     args: [{ type: 'Untyped', kind: 'NameEx', name: 'UNIT' }],
                 }
+                const childHints: any[] =
+                    (hint ?? {})['enum'] ?? Array(v.length).fill(undefined)
+                childHints[0] = 'Str'
                 return {
                     type: 'Untyped',
                     kind: 'OperEx',
                     oper: 'Variants!Variant',
                     args:
                         v.length > 1
-                            ? v.map((arg) => tlaJsonOfNative(arg))
-                            : [...v.map(tlaJsonApplication), tlaUnit],
+                            ? v.map((arg, i) =>
+                                  tlaJsonOfNative(arg, forceVec, childHints[i])
+                              )
+                            : [
+                                  ...v.map((x) => tlaJsonApplication(x, [])),
+                                  tlaUnit,
+                              ],
                 }
             } else {
                 assert(false, `Unexpected native value: ${v}`)
@@ -287,16 +335,26 @@ export function tlaJsonOfNative(v: any, forceVec: boolean = false): any {
                 (key) => typeof key === 'string' && isTlaName(key)
             )
         ) {
+            const entries = Object.entries(v)
+            const flatEntries: any[] = entries.flat()
+            const childHints = entries
+                .map((arg) => {
+                    const k: string = arg[0]
+                    return ['Str', (hint ?? {})[k]]
+                })
+                .flat()
+
             return {
                 type: 'Untyped',
                 kind: 'OperEx',
                 oper: 'RECORD',
-                args: Object.entries(v)
-                    .flat()
-                    .map((arg) => tlaJsonOfNative(arg)),
+                args: flatEntries.map((arg, i) =>
+                    tlaJsonOfNative(arg, forceVec, childHints[i])
+                ),
             }
         }
         // { "2": 3, "4": 5 }  ~~>  SetAsFun({ <<"2", 3>>, <<"4", 5>> })
+        const childHints = (hint ?? {})['map']
         return {
             type: 'Untyped',
             kind: 'OperEx',
@@ -307,7 +365,7 @@ export function tlaJsonOfNative(v: any, forceVec: boolean = false): any {
                     kind: 'OperEx',
                     oper: 'SET_ENUM',
                     args: Object.entries(v).map(([key, value]) =>
-                        tlaJsonOfNative([key, value], true)
+                        tlaJsonOfNative([key, value], true, childHints)
                     ),
                 },
             ],

solarkraft/src/main.ts

@@ -38,6 +38,11 @@ const fetchCmd = {
                 type: 'string',
                 require: true,
             })
+            .option('typemap', {
+                desc: 'File containing contract method type annotations',
+                type: 'string',
+                require: false,
+            })
             .option('rpc', {
                 desc: 'URL of a Horizon endpoint',
                 type: 'string',

solarkraft/test/e2e/fetch.test.ts

@@ -5,6 +5,15 @@ import { describe, it } from 'mocha'
 import { spawn } from 'nexpect'
 
 describe('fetch', () => {
+    it('fails to fetch when provided typemap does not exist', function (done) {
+        this.timeout(50000)
+        spawn(
+            'solarkraft fetch --typemap bogusFile --rpc https://horizon-testnet.stellar.org --id CC22QGTOUMERDNIYN7TPNX3V6EMPHQXVSRR3XY56EADF7YTFISD2ROND --height 1638368 --timeout 10'
+        )
+            .wait('[Error]')
+            .run(done)
+    })
+
     it('fetches transactions', function (done) {
         this.timeout(50000)
         spawn(