@stellar-expert/tx-meta-effects-parser 5.0.0-beta10

package/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+    presets: [['@babel/preset-env', {targets: {node: 'current'}}]]
+}

package/jest.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+    clearMocks: true,
+    transformIgnorePatterns: [],
+    maxWorkers: 1
+    //runner: "jest-runner",
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@stellar-expert/tx-meta-effects-parser",
+  "version": "5.0.0-beta10",
+  "description": "Low-level effects parser for Stellar transaction results and meta XDR",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "jest"
+  },
+  "author": "team@stellar.expert",
+  "license": "MIT",
+  "peerDependencies": {
+    "@stellar/stellar-base": "^10.0.1"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.22.9",
+    "@babel/preset-env": "^7.22.9",
+    "@stellar-expert/eslint-config-js": "^1.1.0",
+    "babel-jest": "^29.6.1",
+    "jest": "^29.6.1"
+  }
+}

package/src/analyzer-primitives.js

@@ -0,0 +1,150 @@
+const {StrKey} = require('@stellar/stellar-base')
+const effectTypes = require('./effect-types')
+const {UnexpectedTxMetaChangeError} = require('./errors')
+
+/**
+ * Returns true for AlphaNum4/12 assets adn false otherwise
+ * @param {String} asset
+ */
+function isAsset(asset) {
+    return asset.includes('-') //lazy check for {code}-{issuer}-{type} format
+}
+
+
+/**
+ * Convert value in stroops (Int64 amount) to the normal string representation
+ * @param {String|Number|BigInt} valueInStroops
+ * @return {String}
+ */
+function fromStroops(valueInStroops) {
+    try {
+        let parsed = typeof valueInStroops === 'bigint' ?
+            valueInStroops :
+            BigInt(valueInStroops.toString())
+        let negative = false
+        if (parsed < 0n) {
+            negative = true
+            parsed *= -1n
+        }
+        const int = parsed / 10000000n
+        const fract = parsed % 10000000n
+        let res = int.toString()
+        if (fract) {
+            res += '.' + fract.toString().padStart(7, '0')
+        }
+        if (negative) {
+            res = '-' + res
+        }
+        return trimZeros(res)
+    } catch (e) {
+        return '0'
+    }
+}
+
+
+/**
+ * Convert arbitrary stringified amount to int64 representation
+ * @param {String|Number} value
+ * @return {BigInt}
+ */
+function toStroops(value) {
+    if (!value)
+        return 0n
+    if (typeof value === 'number') {
+        value = value.toFixed(7)
+    }
+    if (typeof value !== 'string' || !/^-?[\d.,]+$/.test(value))
+        return 0n //invalid format
+    try {
+        let [int, decimal = '0'] = value.split('.', 2)
+        let negative = false
+        if (int.startsWith('-')) {
+            negative = true
+            int = int.slice(1)
+        }
+        let res = BigInt(int) * 10000000n + BigInt(decimal.slice(0, 7).padEnd(7, '0'))
+        if (negative) {
+            res *= -1n
+            if (res < -0x8000000000000000n) //overflow
+                return 0n
+        } else if (res > 0xFFFFFFFFFFFFFFFFn) //overflow
+            return 0n
+        return res
+    } catch (e) {
+        return 0n
+    }
+}
+
+/**
+ * Trim trailing fractional zeros from a string amount representation
+ * @param {String} value
+ * @return {String}
+ * @internal
+ */
+function trimZeros(value) {
+    const [int, fract] = value.split('.')
+    if (!fract)
+        return int
+    const trimmed = fract.replace(/0+$/, '')
+    if (!trimmed.length)
+        return int
+    return int + '.' + trimmed
+}
+
+/**
+ * Replace multiplexed addresses with base G addresses
+ * @param {String} address
+ * @return {String}
+ * @internal
+ */
+function normalizeAddress(address) {
+    const prefix = address[0]
+    if (prefix === 'G')
+        return address //lazy check for ed25519 G address
+    if (prefix !== 'M')
+        throw new TypeError('Expected ED25519 or Muxed address')
+    const rawBytes = StrKey.decodeMed25519PublicKey(address)
+    return StrKey.encodeEd25519PublicKey(rawBytes.subarray(0, 32))
+}
+
+/**
+ * @param {String} action
+ * @param {String} type
+ * @return {String}
+ */
+function encodeSponsorshipEffectName(action, type) {
+    let actionKey
+    switch (action) {
+        case 'created':
+            actionKey = 'Created'
+            break
+        case 'updated':
+            actionKey = 'Updated'
+            break
+        case 'removed':
+            actionKey = 'Removed'
+            break
+        default:
+            throw new UnexpectedTxMetaChangeError({action, type})
+    }
+    return effectTypes[`${type}Sponsorship${actionKey}`]
+}
+
+/**
+ * Check if asset issuer is a source account
+ * @param {String} account
+ * @param {String} asset
+ * @return {Boolean}
+ */
+function isIssuer(account, asset) {
+    return asset.includes(account)
+}
+
+module.exports = {
+    fromStroops,
+    toStroops,
+    normalizeAddress,
+    encodeSponsorshipEffectName,
+    isIssuer,
+    isAsset
+}

package/src/asset-supply-processor.js

@@ -0,0 +1,130 @@
+const effectTypes = require('./effect-types')
+
+/**
+ * Effect supply computation processor
+ */
+class AssetSupplyProcessor {
+    constructor(effects) {
+        this.assetTransfers = {}
+        this.processXlmBalances = effects.some(e => e.type === 'contractInvoked')
+        for (const effect of effects) {
+            this.processEffect(effect)
+        }
+    }
+
+    /**
+     * @type {Object.<String,BigInt>}
+     * @private
+     */
+    assetTransfers
+
+    /**
+     * @type {Boolean}
+     * @private
+     */
+    processXlmBalances = false
+
+    /**
+     * Process generated operation effect
+     * @param {{}} effect
+     */
+    processEffect(effect) {
+        switch (effect.type) {
+            case effectTypes.accountCredited:
+            case effectTypes.claimableBalanceCreated:
+            case effectTypes.assetBurned:
+                //increase supply
+                this.increase(effect.asset, effect.amount)
+                break
+            case effectTypes.accountDebited:
+            case effectTypes.claimableBalanceRemoved:
+            case effectTypes.assetMinted:
+                //decrease supply
+                this.decrease(effect.asset, effect.amount)
+                break
+            case effectTypes.liquidityPoolDeposited:
+                //increase supply for every deposited asset (if liquidity provider is an issuer)
+                for (const {asset, amount} of effect.assets) {
+                    this.increase(asset, amount)
+                }
+                break
+            case effectTypes.liquidityPoolWithdrew:
+                //decrease supply for every deposited asset (if liquidity provider is an issuer)
+                for (const {asset, amount} of effect.assets) {
+                    this.decrease(asset, amount)
+                }
+                break
+            case effectTypes.trade:
+                if (effect.pool) {
+                    for (let i = 0; i < effect.asset.length; i++) {
+                        if (i === 0) { //increase supply if the issuer is seller
+                            this.decrease(effect.asset[i], effect.amount[i])
+                        } else {
+                            this.increase(effect.asset[i], effect.amount[i])
+                        }
+                    }
+                }
+                break
+        }
+    }
+
+    /**
+     * Calculate differences and generate minted/burned effects if needed
+     * @return {{}[]}
+     */
+    resolve() {
+        const res = []
+        for (const [asset, amount] of Object.entries(this.assetTransfers)) {
+            if (amount === 0n)
+                continue
+            const effect = {
+                type: effectTypes.assetMinted,
+                asset
+            }
+            if (amount > 0n) {
+                effect.type = effectTypes.assetMinted
+                effect.amount = amount.toString()
+            }
+            if (amount < 0n) {
+                effect.type = effectTypes.assetBurned
+                effect.amount = (-amount).toString()
+            }
+            res.push(effect)
+        }
+        return res
+    }
+
+    /**
+     * @param {String} asset
+     * @param {String} amount
+     * @private
+     */
+    increase(asset, amount) {
+        if (!this.shouldProcessAsset(asset))
+            return
+        this.assetTransfers[asset] = (this.assetTransfers[asset] || 0n) + BigInt(amount)
+    }
+
+    /**
+     * @param {String} asset
+     * @param {String} amount
+     * @private
+     */
+    decrease(asset, amount) {
+        if (!this.shouldProcessAsset(asset))
+            return
+        this.assetTransfers[asset] = (this.assetTransfers[asset] || 0n) - BigInt(amount)
+    }
+
+    /**
+     * @param {String} asset
+     * @return {Boolean}
+     */
+    shouldProcessAsset(asset) {
+        if (asset === 'XLM') //return true if we process XLM balance changes
+            return this.processXlmBalances
+        return asset.includes('-') || (asset.length === 56 && asset.startsWith('C')) //lazy checks for alphanum4/12 assets and contracts
+    }
+}
+
+module.exports = AssetSupplyProcessor

package/src/contract-preimage-encoder.js

@@ -0,0 +1,43 @@
+const {Asset, StrKey, hash, xdr} = require('@stellar/stellar-base')
+
+const passphraseMapping = {}
+
+/**
+ * Resolve network id hash from a passphrase (with pre-caching)
+ * @param {String} networkPassphrase
+ * @return {Buffer}
+ */
+function getNetworkIdHash(networkPassphrase) {
+    let networkId = passphraseMapping[networkPassphrase]
+    if (!networkId) {
+        networkId = passphraseMapping[networkPassphrase] = hash(Buffer.from(networkPassphrase))
+    }
+    return networkId
+}
+
+/**
+ * Derive ContractId from a wrapped Stellar classic asset
+ * @param {Asset} asset
+ * @param {String} networkPassphrase
+ * @return {String}
+ */
+function contractIdFromAsset(asset, networkPassphrase) {
+    return contractIdFromPreimage(xdr.ContractIdPreimage.contractIdPreimageFromAsset(asset.toXDRObject()), networkPassphrase)
+}
+
+/**
+ * Derive ContractId from a hash preimage
+ * @param {ContractIdPreimage} contractIdPreimage
+ * @param {String} networkPassphrase
+ * @return {String}
+ */
+function contractIdFromPreimage(contractIdPreimage, networkPassphrase) {
+    const hashPreimage = new xdr.HashIdPreimageContractId({
+        networkId: getNetworkIdHash(networkPassphrase),
+        contractIdPreimage
+    })
+    const envelopePreimage = xdr.HashIdPreimage.envelopeTypeContractId(hashPreimage)
+    return StrKey.encodeContract(hash(envelopePreimage.toXDR()))
+}
+
+module.exports = {contractIdFromAsset, contractIdFromPreimage}

package/src/effect-types.js

@@ -0,0 +1,97 @@
+/**
+ * All supported effects types
+ * @readonly
+ */
+const effectTypes = {
+    feeCharged: 'feeCharged',
+
+    accountCreated: 'accountCreated',
+    accountRemoved: 'accountRemoved',
+
+    accountDebited: 'accountDebited',
+    accountCredited: 'accountCredited',
+
+    accountHomeDomainUpdated: 'accountHomeDomainUpdated',
+    accountThresholdsUpdated: 'accountThresholdsUpdated',
+    accountFlagsUpdated: 'accountFlagsUpdated',
+    accountInflationDestinationUpdated: 'accountInflationDestinationUpdated',
+
+    accountSignerUpdated: 'accountSignerUpdated',
+    accountSignerRemoved: 'accountSignerRemoved',
+    accountSignerCreated: 'accountSignerCreated',
+
+    trustlineCreated: 'trustlineCreated',
+    trustlineUpdated: 'trustlineUpdated',
+    trustlineRemoved: 'trustlineRemoved',
+    trustlineAuthorizationUpdated: 'trustlineAuthorizationUpdated',
+
+    assetMinted: 'assetMinted',
+    assetBurned: 'assetBurned',
+
+    liquidityPoolCreated: 'liquidityPoolCreated',
+    liquidityPoolUpdated: 'liquidityPoolUpdated',
+    liquidityPoolRemoved: 'liquidityPoolRemoved',
+
+    offerCreated: 'offerCreated',
+    offerUpdated: 'offerUpdated',
+    offerRemoved: 'offerRemoved',
+
+    trade: 'trade',
+
+    inflation: 'inflation',
+
+    sequenceBumped: 'sequenceBumped',
+
+    dataEntryCreated: 'dataEntryCreated',
+    dataEntryUpdated: 'dataEntryUpdated',
+    dataEntryRemoved: 'dataEntryRemoved',
+
+    claimableBalanceCreated: 'claimableBalanceCreated',
+    claimableBalanceRemoved: 'claimableBalanceRemoved',
+
+    liquidityPoolDeposited: 'liquidityPoolDeposited',
+    liquidityPoolWithdrew: 'liquidityPoolWithdrew',
+
+    accountSponsorshipCreated: 'accountSponsorshipCreated',
+    accountSponsorshipUpdated: 'accountSponsorshipUpdated',
+    accountSponsorshipRemoved: 'accountSponsorshipRemoved',
+
+    trustlineSponsorshipCreated: 'trustlineSponsorshipCreated',
+    trustlineSponsorshipUpdated: 'trustlineSponsorshipUpdated',
+    trustlineSponsorshipRemoved: 'trustlineSponsorshipRemoved',
+
+    offerSponsorshipCreated: 'offerSponsorshipCreated',
+    offerSponsorshipUpdated: 'offerSponsorshipUpdated',
+    offerSponsorshipRemoved: 'offerSponsorshipRemoved',
+
+    dataSponsorshipCreated: 'dataSponsorshipCreated',
+    dataSponsorshipUpdated: 'dataSponsorshipUpdated',
+    dataSponsorshipRemoved: 'dataSponsorshipRemoved',
+
+    claimableBalanceSponsorshipCreated: 'claimableBalanceSponsorshipCreated',
+    claimableBalanceSponsorshipUpdated: 'claimableBalanceSponsorshipUpdated',
+    claimableBalanceSponsorshipRemoved: 'claimableBalanceSponsorshipRemoved',
+
+    liquidityPoolSponsorshipCreated: 'liquidityPoolSponsorshipCreated',
+    liquidityPoolSponsorshipUpdated: 'liquidityPoolSponsorshipUpdated',
+    liquidityPoolSponsorshipRemoved: 'liquidityPoolSponsorshipRemoved',
+
+    signerSponsorshipCreated: 'signerSponsorshipCreated',
+    signerSponsorshipUpdated: 'signerSponsorshipUpdated',
+    signerSponsorshipRemoved: 'signerSponsorshipRemoved',
+
+    contractCodeUploaded: 'contractCodeUploaded',
+
+    contractCreated: 'contractCreated',
+    contractUpdated: 'contractUpdated',
+
+    contractInvoked: 'contractInvoked',
+
+    contractDataCreated: 'contractDataCreated',
+    contractDataUpdated: 'contractDataUpdated',
+    contractDataRemoved: 'contractDataRemoved',
+
+    contractEvent: 'contractEvent'
+}
+
+module.exports = effectTypes

package/src/effect.js

@@ -0,0 +1,24 @@
+class Effect {
+    constructor(type, source) {
+    }
+
+    /**
+     * @type {String}
+     * @readonly
+     */
+    type
+
+    /**
+     * @type {String}
+     * @readonly
+     */
+    source
+
+    toString() {
+        return this.toJSON()
+    }
+
+    toJSON() {
+
+    }
+}

package/src/errors.js

@@ -0,0 +1,13 @@
+class TxMetaEffectParserError extends Error {
+    constructor(message) {
+        super('Transaction metadata processing error. ' + message)
+    }
+}
+
+class UnexpectedTxMetaChangeError extends TxMetaEffectParserError {
+    constructor({type, action}) {
+        super(`Unexpected meta changes: "${type}" "${action}"`)
+    }
+}
+
+module.exports = {UnexpectedTxMetaChangeError, TxMetaEffectParserError}