@stellar-expert/tx-meta-effects-parser 6.4.0 → 7.0.0-rc.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stellar-expert/tx-meta-effects-parser",
-  "version": "6.4.0",
+  "version": "7.0.0-rc.10",
   "description": "Low-level effects parser for Stellar transaction results and meta XDR",
   "main": "src/index.js",
   "scripts": {
@@ -9,7 +9,7 @@
   "author": "team@stellar.expert",
   "license": "MIT",
   "peerDependencies": {
-    "@stellar/stellar-base": "^13.0.1"
+    "@stellar/stellar-base": "^14.0.0"
   },
   "devDependencies": {
     "@babel/core": "^7.22.9",

package/src/aggregation/events-analyzer.js

@@ -1,4 +1,4 @@
-const {StrKey} = require('@stellar/stellar-base')
+const {StrKey, encodeMuxedAccount, encodeMuxedAccountToAddress} = require('@stellar/stellar-base')
 const effectTypes = require('../effect-types')
 const {xdrParseScVal, xdrParseAsset, isContractAddress} = require('../parser/tx-xdr-parser-utils')
 const {mapSacContract} = require('./sac-contract-mapper')
@@ -146,15 +146,19 @@ class EventsAnalyzer {
                 if (!matchEventTopicsShape(topics, ['address', 'address', 'str?']))
                     return
                 const from = xdrParseScVal(topics[1])
-                const to = xdrParseScVal(topics[2])
+                const receiver = xdrParseScVal(topics[2])
+                let to = receiver
+                let amount = processEventBodyValue(body.data())
+                if (amount?.amount !== undefined) {
+                    if (amount.to_muxed_id && !to.startsWith('M')) {
+                        to = encodeMuxedAccountToAddress(encodeMuxedAccount(to, amount.to_muxed_id))
+                        amount = amount.amount
+                    }
+                }
+                if (typeof amount!=='string')
+                    return null
                 if (to === from) //self transfer - nothing happens
                     return // TODO: need additional checks
-                const amount = processEventBodyValue(body.data())
-                if (!this.matchInvocationEffect(e =>
-                    (e.function === 'transfer' && matchArrays([from, to, amount], e.args)) ||
-                    (e.function === 'transfer_from' && matchArrays([undefined, from, to, amount], e.args))
-                ))
-                    return
                 let classicAsset
                 if (topics.length > 3) {
                     classicAsset = xdrParseAsset(xdrParseScVal(topics[3]))
@@ -172,7 +176,7 @@ class EventsAnalyzer {
                     if (isContractAddress(to)) {
                         this.effectsAnalyzer.credit(amount, classicAsset, to)
                     }
-                    if (classicAsset.includes(to)) {  //SAC transfer by asset issuer
+                    if (classicAsset.includes(receiver)) {  //SAC transfer by asset issuer
                         this.effectsAnalyzer.burn(classicAsset, amount)
                     }
                 } else { //other cases
@@ -182,14 +186,21 @@ class EventsAnalyzer {
             }
                 break
             case 'mint': {
-                if (!matchEventTopicsShape(topics, ['address', 'address', 'str?']))
+                if (!matchEventTopicsShape(topics, ['address', 'address', 'str?']) && !matchEventTopicsShape(topics, ['address', 'str?']))
                     return //throw new Error('Non-standard event')
-                const to = xdrParseScVal(topics[2])
-                const amount = processEventBodyValue(body.data())
-                if (!this.matchInvocationEffect(e => e.function === 'mint' && matchArrays([to, amount], e.args)))
-                    return
-                if (topics.length > 3) {
-                    mapSacContract(this.effectsAnalyzer, contract, xdrParseAsset(xdrParseScVal(topics[3])))
+                let to = xdrParseScVal(topics[topics[2]?._arm === 'address' ? 2 : 1])
+                let amount = processEventBodyValue(body.data())
+                if (amount?.amount !== undefined) {
+                    if (amount.to_muxed_id && !to.startsWith('M')) {
+                        to = encodeMuxedAccountToAddress(encodeMuxedAccount(to, amount.to_muxed_id))
+                        amount = amount.amount
+                    }
+                }
+                if (typeof amount !== 'string')
+                    return null
+                const last = topics[topics.length - 1]
+                if (last._arm === 'str') {
+                    mapSacContract(this.effectsAnalyzer, contract, xdrParseAsset(xdrParseScVal(last)))
                 }
                 const asset = this.effectsAnalyzer.resolveAsset(contract)
                 this.effectsAnalyzer.mint(asset, amount)
@@ -203,13 +214,8 @@ class EventsAnalyzer {
                     return //throw new Error('Non-standard event')
                 const from = xdrParseScVal(topics[1])
                 const amount = processEventBodyValue(body.data())
-                if (!amount)
-                    return
-                if (!this.matchInvocationEffect(e =>
-                    (e.function === 'burn' && matchArrays([from, amount], e.args)) ||
-                    (e.function === 'burn_from' && matchArrays([undefined, from, amount], e.args))
-                ))
-                    return
+                if (typeof amount !== 'string')
+                    return null
                 if (topics.length > 2) {
                     mapSacContract(this.effectsAnalyzer, contract, xdrParseAsset(xdrParseScVal(topics[2])))
                 }
@@ -221,12 +227,12 @@ class EventsAnalyzer {
             }
                 break
             case 'clawback': {
-                if (!matchEventTopicsShape(topics, ['address', 'address', 'str?']))
+                if (!matchEventTopicsShape(topics, ['address', 'address', 'str?']) && !matchEventTopicsShape(topics, ['address', 'str?']))
                     return //throw new Error('Non-standard event')
-                const from = xdrParseScVal(topics[2])
+                const from = xdrParseScVal(topics[topics[2]?._arm === 'address' ? 2 : 1])
                 const amount = processEventBodyValue(body.data())
-                if (!this.matchInvocationEffect(e => e.function === 'clawback' && matchArrays([from, amount], e.args)))
-                    return
+                if (typeof amount !== 'string')
+                    return null
                 if (topics.length > 3) {
                     mapSacContract(this.effectsAnalyzer, contract, xdrParseAsset(xdrParseScVal(topics[3])))
                 }
@@ -240,15 +246,14 @@ class EventsAnalyzer {
                     return //throw new Error('Non-standard event')
                 const currentAdmin = xdrParseScVal(topics[1])
                 const newAdmin = processEventBodyValue(body.data())
-                if (!this.matchInvocationEffect(e => e.function === 'set_admin' && matchArrays([currentAdmin, newAdmin], [this.effectsAnalyzer.source, e.args])))
-                    return
                 if (topics.length > 2) {
                     mapSacContract(this.effectsAnalyzer, contract, xdrParseAsset(xdrParseScVal(topics[2])))
                 }
                 this.effectsAnalyzer.setAdmin(contract, newAdmin)
             }
                 break
-            /*case 'approve': { //TODO: think about processing this effect
+            /*case 'set_authorized':*/ //TODO: think about processing this effects
+            /*case 'approve': {
                 if (!matchEventTopicsShape(topics, ['address', 'address', 'str?']))
                     throw new Error('Non-standard event')
                 const from = xdrParseScVal(topics[1])
@@ -260,12 +265,14 @@ class EventsAnalyzer {
                 break*/
         }
     }
-
-    matchInvocationEffect(cb) {
-        return this.effectsAnalyzer.effects.find(e => e.type === effectTypes.contractInvoked && cb(e))
-    }
 }
 
+/**
+ * Compare types in the topics array with expected values
+ * @param {ScVal[]} topics
+ * @param {string[]} shape
+ * @return {boolean}
+ */
 function matchEventTopicsShape(topics, shape) {
     if (topics.length > shape.length + 1)
         return false
@@ -287,24 +294,14 @@ function matchEventTopicsShape(topics, shape) {
     return true
 }
 
-function matchArrays(a, b) {
-    if (!a || !b)
-        return false
-    if (a.length !== b.length)
-        return false
-    for (let i = a.length; i--;) {
-        if (a[i] !== undefined && a[i] !== b[i]) //undefined serves as * substitution
-            return false
-    }
-    return true
-}
-
+/**
+ * Retrieve event body value
+ * @param value
+ */
 function processEventBodyValue(value) {
     const innerValue = value.value()
-    /*if (innerValue instanceof Array) //handle simple JS arrays
-        return innerValue.map(xdrParseScVal)*/
     if (!innerValue) //scVoid
-        return undefined
+        return null
     return xdrParseScVal(value) //other scValue
 }
 

package/src/aggregation/sac-contract-mapper.js

@@ -24,12 +24,16 @@ function mapSacContract(effectsAnalyzer, contractAddress, classicAsset) {
     //try to load from cache first
     const fromCache = sacCache.get(classicAsset + network)
     if (!fromCache) {
-        const encodedContract = contractIdFromAsset(toStellarAsset(classicAsset), network)
-        sacCache.set(classicAsset + network, contractAddress)
-        if (contractAddress === undefined) {
-            contractAddress = encodedContract
-        } else if (encodedContract !== contractAddress)
+        try {
+            const encodedContract = contractIdFromAsset(toStellarAsset(classicAsset), network)
+            sacCache.set(classicAsset + network, contractAddress)
+            if (contractAddress === undefined) {
+                contractAddress = encodedContract
+            } else if (encodedContract !== contractAddress)
+                return false
+        } catch (e) {
             return false
+        }
     } else if (contractAddress !== fromCache)
         return false //check whether validated contract from cache matches the asset
     if (sacMap) {

package/src/effect-types.js

@@ -82,9 +82,11 @@ const effectTypes = {
 
     contractCodeUploaded: 'contractCodeUploaded',
     contractCodeRemoved: 'contractCodeRemoved',
+    contractCodeRestored: 'contractCodeRestored',
 
     contractCreated: 'contractCreated',
     contractUpdated: 'contractUpdated',
+    contractRestored: 'contractRestored',
 
     contractInvoked: 'contractInvoked',
     contractError: 'contractError',
@@ -92,6 +94,7 @@ const effectTypes = {
     contractDataCreated: 'contractDataCreated',
     contractDataUpdated: 'contractDataUpdated',
     contractDataRemoved: 'contractDataRemoved',
+    contractDataRestored: 'contractDataRestored',
 
     contractEvent: 'contractEvent',
     contractMetrics: 'contractMetrics',

package/src/effects-analyzer.js

@@ -2,13 +2,13 @@ const {StrKey, hash, xdr, nativeToScVal} = require('@stellar/stellar-base')
 const effectTypes = require('./effect-types')
 const {parseLedgerEntryChanges} = require('./parser/ledger-entry-changes-parser')
 const {xdrParseAsset, xdrParseAccountAddress, xdrParseScVal} = require('./parser/tx-xdr-parser-utils')
-const {analyzeSignerChanges} = require('./aggregation/signer-changes-analyzer')
 const {contractIdFromPreimage} = require('./parser/contract-preimage-encoder')
+const {generateContractCodeEntryHash} = require('./parser/ledger-key')
+const {analyzeSignerChanges} = require('./aggregation/signer-changes-analyzer')
 const EventsAnalyzer = require('./aggregation/events-analyzer')
 const AssetSupplyAnalyzer = require('./aggregation/asset-supply-analyzer')
 const {mapSacContract} = require('./aggregation/sac-contract-mapper')
 const {UnexpectedTxMetaChangeError, TxMetaEffectParserError} = require('./errors')
-const {generateContractCodeEntryHash} = require('./parser/ledger-key')
 
 class EffectsAnalyzer {
     constructor({
@@ -491,6 +491,7 @@ class EffectsAnalyzer {
             const effect = {}
             switch (action) {
                 case 'created':
+                case 'restored':
                     if (!after.sponsor)
                         continue
                     effect.sponsor = after.sponsor
@@ -823,13 +824,12 @@ class EffectsAnalyzer {
     }
 
     processContractChanges({action, before, after}) {
-        if (action !== 'created' && action !== 'updated')
-            throw new UnexpectedTxMetaChangeError({type: 'contract', action})
         const {kind, owner: contract, keyHash} = after
         let effect = {
             type: effectTypes.contractCreated,
             contract,
-            kind
+            kind,
+            keyHash
         }
         switch (kind) {
             case 'fromAsset':
@@ -841,22 +841,30 @@ class EffectsAnalyzer {
             default:
                 throw new TxMetaEffectParserError('Unexpected contract type: ' + kind)
         }
-        if (action === 'created') {
-            if (this.effects.some(e => e.type === effectTypes.contractCreated && e.contract === contract)) {
-                effect = undefined //skip contract creation effects processed by top-level createContract operation call
-            }
-        } else if (action === 'updated') {
-            effect.type = effectTypes.contractUpdated
-            effect.prevWasmHash = before.wasmHash
-            if (before.wasmHash === after.wasmHash) {//skip if hash unchanged
-                effect = undefined
-            }
+        switch (action) {
+            case 'created':
+                if (this.effects.some(e => e.type === effectTypes.contractCreated && e.contract === contract)) {
+                    effect = undefined //skip contract creation effects processed by top-level createContract operation call
+                }
+                break
+            case 'updated':
+                effect.type = effectTypes.contractUpdated
+                effect.prevWasmHash = before.wasmHash
+                if (before.wasmHash === after.wasmHash) {//skip if hash unchanged
+                    effect = undefined
+                }
+                break
+            case 'restored':
+                effect.type = effectTypes.contractRestored
+                break
+            default:
+                throw new UnexpectedTxMetaChangeError({type: 'contract', action})
         }
         if (effect) {
             this.addEffect(effect, effect.type === effectTypes.contractCreated ? 0 : undefined)
         }
         if (before?.storage?.length || after?.storage?.length) {
-            this.processInstanceDataChanges(before, after)
+            this.processInstanceDataChanges(before, after, action === 'restored')
         }
     }
 
@@ -885,6 +893,10 @@ class EffectsAnalyzer {
                 effect.type = effectTypes.contractDataRemoved
                 effect.prevValue = before.value
                 break
+            case 'restored':
+                effect.type = effectTypes.contractDataRestored
+                effect.value = after.value
+                break
         }
         this.addEffect(effect)
         this.processContractBalance(effect)
@@ -898,17 +910,23 @@ class EffectsAnalyzer {
             case 'updated':
                 break //it doesn't change the state
             case 'removed':
-                const effect = {
+                this.addEffect({
                     type: effectTypes.contractCodeRemoved,
                     wasmHash: hash,
                     keyHash
-                }
-                this.addEffect(effect)
+                })
+                break
+            case 'restored':
+                this.addEffect({
+                    type: effectTypes.contractCodeRestored,
+                    wasmHash: hash,
+                    keyHash
+                })
                 break
         }
     }
 
-    processInstanceDataChanges(before, after) {
+    processInstanceDataChanges(before, after, restored) {
         const storageBefore = before?.storage || []
         const storageAfter = [...(after?.storage || [])]
         for (const {key, val} of storageBefore) {
@@ -948,7 +966,7 @@ class EffectsAnalyzer {
         //iterate all storage items left
         for (const {key, val} of storageAfter) {
             const effect = {
-                type: effectTypes.contractDataCreated,
+                type: restored ? effectTypes.contractDataRestored : effectTypes.contractDataCreated,
                 owner: after?.owner || before.owner,
                 key,
                 value: val,
@@ -969,12 +987,17 @@ class EffectsAnalyzer {
             ttl
         }
         if (stateEffect) {
-            if (stateEffect.type.includes('contractCode')) {
+            if (stateEffect.type.startsWith('contractCode')) {
                 effect.kind = 'contractCode'
-            } else if (stateEffect.type.includes('contractData')) {
+            } else if (stateEffect.type.startsWith('contractData')) {
                 effect.kind = 'contractData'
                 effect.owner = stateEffect.owner
-            }
+            } else if (stateEffect.type.startsWith('contract')) {
+                effect.kind = 'contractData'
+                effect.owner = stateEffect.contract
+            } else
+                throw new UnexpectedTxMetaChangeError({type: 'ttl', action: stateEffect.type})
+            stateEffect.ttl = ttl
         }
         this.addEffect(effect)
     }
@@ -1100,6 +1123,9 @@ function encodeSponsorshipEffectName(action, type) {
         case 'removed':
             actionKey = 'Removed'
             break
+        case 'restored':
+            actionKey = 'Restored'
+            break
         default:
             throw new UnexpectedTxMetaChangeError({action, type})
     }

package/src/index.js

@@ -139,6 +139,8 @@ function parseTxOperationsMeta({
     }
     const metaValue = meta.value()
     const opMeta = metaValue.operations()
+    const isV4Meta = meta.arm() === 'v4'
+    let txEvents = isV4Meta ? metaValue.events() : undefined
 
     //analyze operation effects for each operation
     for (let i = 0; i < parsedTx.operations.length; i++) {
@@ -155,12 +157,23 @@ function parseTxOperationsMeta({
             const isSorobanInvocation = operation.type === 'invokeHostFunction'
             //only for Soroban contract invocation
             if (isSorobanInvocation) {
-                const sorobanMeta = metaValue._attributes.sorobanMeta
+                const {sorobanMeta} = metaValue._attributes
                 if (sorobanMeta) {
-                    params.events = sorobanMeta.events()
-                    params.diagnosticEvents = sorobanMeta.diagnosticEvents()
+                    if (sorobanMeta.events) {
+                        params.events = sorobanMeta.events()
+                    }
+                    if (sorobanMeta.diagnosticEvents) {
+                        params.diagnosticEvents = sorobanMeta.diagnosticEvents()
+                    }
                     params.processSystemEvents = processSystemEvents
                 }
+                if (isV4Meta) {
+                    params.diagnosticEvents = metaValue.diagnosticEvents()
+                    const invocationOp = metaValue.operations()[0]
+                    if (invocationOp) {
+                        params.events = invocationOp.events()
+                    }
+                }
                 params.mapSac = mapSac
             }
             const analyzer = new EffectsAnalyzer(params)

package/src/parser/ledger-entry-changes-parser.js

@@ -6,7 +6,7 @@ const {generateContractStateEntryHash, generateContractCodeEntryHash} = require(
 /**
  * @typedef {{}} ParsedLedgerEntryMeta
  * @property {'account'|'trustline'|'offer'|'data'|'liquidityPool'|'claimableBalance'|'contractData'|'contractCode'|'ttl'} type - Ledger entry type
- * @property {'created'|'updated'|'removed'} action - Ledger modification action
+ * @property {'created'|'updated'|'removed'|'restored'} action - Ledger modification action
  * @property {{}} before - Ledger entry state before changes applied
  * @property {{}} after - Ledger entry state after changes application
  */
@@ -18,14 +18,15 @@ const {generateContractStateEntryHash, generateContractCodeEntryHash} = require(
 function parseLedgerEntryChanges(ledgerEntryChanges) {
     const changes = []
     let state
+    let containsTtl = false
     for (let i = 0; i < ledgerEntryChanges.length; i++) {
         const entry = ledgerEntryChanges[i]
         const action = entry._arm
         const stateData = parseEntry(entry, action)
         if (stateData === undefined)
             continue
-        const change = {action}
         const type = entry._value._arm
+        const change = {action, type}
         switch (action) {
             case 'state':
                 state = stateData
@@ -44,6 +45,11 @@ function parseLedgerEntryChanges(ledgerEntryChanges) {
                 change.after = stateData
                 change.type = stateData.entry
                 break
+            case 'restored':
+                change.before = state
+                change.after = stateData
+                change.type = stateData.entry
+                break
             case 'removed':
                 if (!state && type === 'ttl')
                     continue //skip expiration processing for now
@@ -54,9 +60,17 @@ function parseLedgerEntryChanges(ledgerEntryChanges) {
             default:
                 throw new TxMetaEffectParserError(`Unknown change entry type: ${action}`)
         }
+        if (change.type === 'ttl') {
+            containsTtl = true
+        }
         changes.push(change)
         state = null
     }
+    if (containsTtl) { //put ttl entries into the end of array
+        changes.sort((a, b) =>
+            a.type !== 'ttl' && b.type === 'ttl' ?
+                -1 : 0)
+    }
     return changes
 }
 

package/src/parser/tx-meta-changes-parser.js

@@ -16,6 +16,7 @@ function parseTxMetaChanges(meta) {
             break
         case 'v2':
         case 'v3':
+        case 'v4':
             retrieveTopLevelChanges(transactionMeta.txChangesBefore(), txMetaChanges)
             retrieveTopLevelChanges(transactionMeta.txChangesAfter(), txMetaChanges)
             break

package/src/parser/tx-xdr-parser-utils.js

@@ -1,4 +1,4 @@
-const {StrKey, LiquidityPoolId, scValToBigInt, xdr, Asset} = require('@stellar/stellar-base')
+const {xdr, StrKey, LiquidityPoolId, Asset, scValToBigInt, encodeMuxedAccount, encodeMuxedAccountToAddress} = require('@stellar/stellar-base')
 const {TxMetaEffectParserError} = require('../errors')
 
 /**
@@ -26,10 +26,9 @@ function toStellarAsset(assetDescriptor) {
 /**
  * Parse account address from XDR representation
  * @param accountId
- * @param muxedAccountsSupported
- * @return {String|{muxedId: String, primary: String}}
+ * @return {String}
  */
-function xdrParseAccountAddress(accountId, muxedAccountsSupported = false) {
+function xdrParseAccountAddress(accountId) {
     if (!accountId)
         return undefined
     if (accountId.arm) {
@@ -37,8 +36,6 @@ function xdrParseAccountAddress(accountId, muxedAccountsSupported = false) {
             case 'ed25519':
                 return StrKey.encodeEd25519PublicKey(accountId.ed25519())
             case 'med25519':
-                if (!muxedAccountsSupported)
-                    throw new TxMetaEffectParserError(`Muxed accounts not supported here`)
                 return {
                     primary: StrKey.encodeEd25519PublicKey(accountId.value().ed25519()),
                     muxedId: accountId.value().id().toString()
@@ -53,6 +50,17 @@ function xdrParseAccountAddress(accountId, muxedAccountsSupported = false) {
     throw new TypeError(`Failed to identify and parse account address: ${accountId}`)
 }
 
+/**
+ * Parse muxed account address from ScAddress XDR representation
+ * @param {{}} value
+ * @return {string}
+ */
+function xdrParseMuxedScAddress(value) {
+    const {ed25519, id} = value._attributes
+    const muxed = encodeMuxedAccount(StrKey.encodeEd25519PublicKey(ed25519), id._value.toString())
+    return encodeMuxedAccountToAddress(muxed)
+}
+
 /**
  * Parse Contract ID from raw bytes
  * @param {Buffer} rawContractId
@@ -257,11 +265,15 @@ function xdrParseScVal(value, treatBytesAsContractId = false) {
         case 'duration':
             return scValToBigInt(value).toString()
         case 'address':
-            if (value._value._arm === 'accountId')
-                return xdrParseAccountAddress(value._value.value())
-            if (value._value._arm === 'contractId')
-                return xdrParseContractAddress(value._value.value())
-            throw new TxMetaEffectParserError('Not supported XDR primitive type: ' + value.toString())
+            switch (value._value._arm) {
+                case 'accountId':
+                    return xdrParseAccountAddress(value._value.value())
+                case 'contractId':
+                    return xdrParseContractAddress(value._value.value())
+                case 'muxedAccount':
+                    return xdrParseMuxedScAddress(value._value.value())
+            }
+            throw new TxMetaEffectParserError('Not supported XDR primitive type: ' + value._value._arm.toString())
         case 'bytes':
             return treatBytesAsContractId ? xdrParseContractAddress(value.value()) : value._value.toString('base64')
         case 'i32':
@@ -298,6 +310,7 @@ module.exports = {
     xdrParseAsset,
     xdrParseAccountAddress,
     xdrParseContractAddress,
+    xdrParseMuxedScAddress,
     xdrParseClaimant,
     xdrParseClaimedOffer,
     xdrParseTradeAtom,