@stellar-expert/contract-wasm-interface-parser 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 StellarExpert Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/index.js

@@ -0,0 +1,38 @@
+import {xdr} from '@stellar/stellar-base'
+import {XdrReader} from './src/xdr-reader'
+import {WasmSectionReader} from './src/wasm-section-reader'
+import {parseContractMeta, parseSpec} from './src/xdr-spec-parser'
+
+/**
+ * Parse contract metadata from WASM sections
+ * @param {Buffer} rawWasm
+ * @return {{}}
+ */
+export function parseContractMetadata(rawWasm) {
+    const wasmSectionReader = new WasmSectionReader(rawWasm)
+    const sections = wasmSectionReader.readCustomSections()
+    const res = {}
+    for (const section of sections) {
+        switch (section.name) {
+            case 'contractenvmetav0':
+                res.interfaceVersion = xdr.ScEnvMetaEntry.fromXDR(section.contents).value().toString()
+                break
+            case 'contractmetav0':
+                Object.assign(res, parseContractMeta(parseEntries(section.contents, xdr.ScMetaEntry)))
+                break
+            case 'contractspecv0':
+                Object.assign(res, parseSpec(parseEntries(section.contents, xdr.ScSpecEntry)))
+                break
+        }
+    }
+    return res
+}
+
+function parseEntries(buffer, xdrContract) {
+    const reader = new XdrReader(buffer)
+    const entries = []
+    while (!reader.eof) {
+        entries.push(xdrContract.read(reader))
+    }
+    return entries
+}

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@stellar-expert/contract-wasm-interface-parser",
+  "version": "1.0.0",
+  "description": "Contract interface metadata parser for binary WASM",
+  "main": "index.js",
+  "module": "./index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stellar-expert/contract-wasm-interface-parser.git"
+  },
+  "author": "orbitlens <orbit@stellar.expert>",
+  "license": "MIT",
+  "peerDependencies": {
+    "@stellar/stellar-base": "^10.0.1"
+  }
+}

package/src/wasm-section-reader.js

@@ -0,0 +1,79 @@
+/**
+ * Minimalistic WASM metadata reader
+ */
+export class WasmSectionReader {
+    constructor(data) {
+        this.data = data
+    }
+
+    /**
+     * @type {Buffer}
+     * @private
+     */
+    data
+    /**
+     * Current reader position
+     * @type {number}
+     * @private
+     */
+    pointer = 8
+
+    /**
+     * Read custom metadata sections from raw WASM
+     * @return {{name: string, contents: Buffer}[]}
+     */
+    readCustomSections() {
+        const sections = []
+        while (this.pointer < this.data.length) {
+            const sectionType = this.readUint8()
+            let length = this.readVarUint32()
+            if (sectionType === 0) { //accumulate only custom sections
+                const sectionStart = this.pointer
+                const name = this.readString()
+                length -= this.pointer - sectionStart
+                sections.push({
+                    name,
+                    contents: this.data.subarray(this.pointer, this.pointer + length)
+                })
+            }
+            this.pointer += length
+        }
+        return sections
+    }
+
+    /**
+     * @return {number}
+     * @private
+     */
+    readUint8() {
+        return this.data.readUint8(this.pointer++)
+    }
+
+    /**
+     * @return {number}
+     * @private
+     */
+    readVarUint32() {
+        let result = 0
+        let shift = 0
+        while (true) {
+            let byte = this.readUint8()
+            result |= (byte & 0x7f) << shift
+            shift += 7
+            if ((byte & 0x80) === 0)
+                break
+        }
+        return result >>> 0
+    }
+
+    /**
+     * @return {string}
+     * @private
+     */
+    readString() {
+        const length = this.readVarUint32()
+        const contents = this.data.subarray(this.pointer, this.pointer + length)
+        this.pointer += length
+        return contents.toString('utf-8')
+    }
+}

package/src/xdr-reader.js

@@ -0,0 +1,148 @@
+export class XdrReader {
+    /**
+     * @constructor
+     * @param {Buffer} source - Buffer containing serialized data
+     */
+    constructor(source) {
+        if (!Buffer.isBuffer(source)) {
+            if (source instanceof Array) {
+                source = Buffer.from(source)
+            } else
+                throw new Error('Source not specified')
+        }
+
+        this._buffer = source
+        this._length = source.length
+        this._index = 0
+    }
+
+    /**
+     * @type {Buffer}
+     * @private
+     * @readonly
+     */
+    _buffer
+    /**
+     * @type {Number}
+     * @private
+     * @readonly
+     */
+    _length
+    /**
+     * @type {Number}
+     * @private
+     * @readonly
+     */
+    _index
+
+    /**
+     * Check if the reader reached the end of the input buffer
+     * @return {Boolean}
+     */
+    get eof() {
+        return this._index === this._length
+    }
+
+    /**
+     * Advance reader position, check padding and overflow
+     * @param {Number} size - Bytes to read
+     * @return {Number} Position to read from
+     * @private
+     */
+    advance(size) {
+        const from = this._index
+        // advance cursor position
+        this._index += size
+        // check buffer boundaries
+        if (this._length < this._index)
+            throw new Error(
+                'attempt to read outside the boundary of the buffer'
+            )
+        // check that padding is correct for Opaque and String
+        const padding = 4 - (size % 4 || 4)
+        if (padding > 0) {
+            for (let i = 0; i < padding; i++)
+                if (this._buffer[this._index + i] !== 0)
+                    // all bytes in the padding should be zeros
+                    throw new Error('Invalid padding')
+            this._index += padding
+        }
+        return from
+    }
+
+    /**
+     * Reset reader position
+     * @return {void}
+     */
+    rewind() {
+        this._index = 0
+    }
+
+    /**
+     * Read byte array from the buffer
+     * @param {Number} size - Bytes to read
+     * @return {Buffer} - Sliced portion of the underlying buffer
+     */
+    read(size) {
+        const from = this.advance(size)
+        return this._buffer.subarray(from, from + size)
+    }
+
+    /**
+     * Read i32 from buffer
+     * @return {Number}
+     */
+    readInt32BE() {
+        return this._buffer.readInt32BE(this.advance(4))
+    }
+
+    /**
+     * Read u32 from buffer
+     * @return {Number}
+     */
+    readUInt32BE() {
+        return this._buffer.readUInt32BE(this.advance(4))
+    }
+
+    /**
+     * Read i64 from buffer
+     * @return {BigInt}
+     */
+    readBigInt64BE() {
+        return this._buffer.readBigInt64BE(this.advance(8))
+    }
+
+    /**
+     * Read u64 from buffer
+     * @return {BigInt}
+     */
+    readBigUInt64BE() {
+        return this._buffer.readBigUInt64BE(this.advance(8))
+    }
+
+    /**
+     * Read float from buffer
+     * @return {Number}
+     */
+    readFloatBE() {
+        return this._buffer.readFloatBE(this.advance(4))
+    }
+
+    /**
+     * Read double from buffer
+     * @return {Number}
+     */
+    readDoubleBE() {
+        return this._buffer.readDoubleBE(this.advance(8))
+    }
+
+    /**
+     * Ensure that input buffer has been consumed in full, otherwise it's a type mismatch
+     * @return {void}
+     * @throws {Error}
+     */
+    ensureInputConsumed() {
+        if (this._index !== this._length)
+            throw new Error(`Invalid XDR contract typecast - source buffer not entirely consumed`)
+    }
+}

package/src/xdr-spec-parser.js

@@ -0,0 +1,121 @@
+export function parseContractMeta(meta) {
+    const res = {}
+    for (const {_value} of meta) {
+        const key = _value.key().toString()
+        const val = _value.val().toString()
+        switch (key) {
+            case 'rsver':
+                res.rustVersion = val
+                break
+            case 'rssdkver':
+                res.sdkVersion = val
+                break
+        }
+    }
+    return res
+}
+
+export function parseSpec(entries) {
+    const res = {}
+
+    function addSpec(key, descriptor) {
+        let spec = res[key]
+        if (spec === undefined) {
+            spec = res[key] = []
+        }
+        spec.push(descriptor)
+    }
+
+    for (const spec of entries) {
+        const value = spec.value()
+        switch (spec._arm) {
+            case 'functionV0':
+                addSpec('functions', {
+                    name: value.name().toString(),
+                    inputs: value.inputs().map(parseParameter),
+                    outputs: value.outputs().map(parseParameterType)
+                })
+                break
+            case 'udtStructV0':
+                addSpec('structs', {
+                    name: parseStructName(value),
+                    fields: value.fields().map(parseParameter)
+                })
+                break
+            case 'udtUnionV0':
+                addSpec('unions', {
+                    name: parseStructName(value),
+                    cases: value.cases().reduce((agg, c) => {
+                        const value = c.value()
+                        const caseType = {
+                            name: value.name().toString()
+                        }
+                        if (value.type) {
+                            caseType.type = value.type().map(parseParameterType)
+                        }
+                        agg[c.switch().name.replace('scSpecUdtUnionCase', '')] = caseType
+                        return agg
+                    }, {})
+                })
+                break
+            case 'udtEnumV0':
+                addSpec('enums', {
+                    name: parseStructName(value),
+                    cases: value.cases().reduce((agg, c) => {
+                        const value = c.value()
+                        agg[value.name().toString()] = value.value() //TODO: check
+                        return agg
+                    }, {})
+                })
+                break
+            case 'udtErrorEnumV0':
+                addSpec('errors', {
+                    name: parseStructName(value),
+                    cases: value.cases().map(c => ({
+                        name: c.name().toString(),
+                        value: c.value()
+                    }))
+                })
+                break
+        }
+    }
+    return res
+}
+
+function parseStructName(value) {
+    let structName = value.name().toString()
+    const lib = value.lib()
+    if (lib.length) {
+        structName += ':' + lib.toString()
+    }
+    return structName
+}
+
+function parseParameterType(type) {
+    const typeName = type.switch().name
+    switch (typeName) {
+        case 'scSpecTypeOption':
+            return `option<${parseParameterType(type.valueType())}>`
+        case 'scSpecTypeBytesN':
+            return `bytesn<${type.value().n()}>`
+        case 'scSpecTypeVec':
+            return `vec<${parseParameterType(type.value().elementType())}>`
+        case 'scSpecTypeMap':
+            return `map<${parseParameterType(type.value().keyType())},${parseParameter(type.value().valueType())}>`
+        case 'scSpecTypeResult':
+            return `result<${parseParameterType(type.value().okType())},${parseParameter(type.value().errorType())}>`
+        case 'scSpecTypeTuple':
+            return `tuple<${type.value().valueTypes().map(parseParameterType).join()}>`
+        case 'scSpecTypeUdt':
+            return `udt<${type.value().name()}>`
+        default:
+            return typeName.replace('scSpecType', '').toLowerCase()
+    }
+}
+
+function parseParameter(param) {
+    return {
+        name: param.name().toString(),
+        type: parseParameterType(param.type())
+    }
+}