wasm-metering

SYNOPSIS

Injects metering into webassembly binaries. The metering counts computation time for a given program in units of gas. The metered wasm binary expects an import that functions as the gas counter. This works for binary version 0x1. For a more detailed description of how this works see metering.md

INSTALL

npm install wasm-metering

USAGE

const fs = require('fs')
const metering = require('wasm-metering')
 
const wasm = fs.readFileSync('fac.wasm')
const meteredWasm = metering.meterWASM(wasm, {
  meterType: 'i32'
})
 
const limit = 90000000
let gasUsed = 0
 
const mod = WebAssembly.Module(meteredWasm.module)
const instance = WebAssembly.Instance(mod, {
  'metering': {
    'usegas': (gas) => {
      gasUsed += gas
      if (gasUsed > limit) {
        throw new Error('out of gas!')
      }
    }
  }
})
 
const result = instance.exports.fac(6)
console.log(`result:${result}, gas used ${gasUsed * 1e-4}`) // result:720, gas used 0.4177

Source

API

meterJSON

./index.js:104-224

Injects metering into a JSON output of wasm2json

Parameters

• json Object the json tobe metered
• opts Object
  • opts.costTable [Object] the cost table to meter with. See these notes about the default. (optional, default defaultTable)
  • opts.moduleStr [String] the import string for the metering function (optional, default 'metering')
  • opts.fieldStr [String] the field string for the metering function (optional, default 'usegas')
  • opts.meterType [String] the register type that is used to meter. Can be i64, i32, f64, f32 (optional, default 'i64')

Returns Object the metered json

meterWASM

./index.js:236-240

Injects metering into a webassembly binary

Parameters

• json Object the json tobe metered
• opts [Object](default {})
  • opts.costTable [Object] the cost table to meter with. See these notes about the default. (optional, default defaultTable)
  • opts.moduleStr [String] the import string for the metering function (optional, default 'metering')
  • opts.fieldStr [String] the field string for the metering function (optional, default 'usegas')
  • opts.meterType [String] the register type that is used to meter. Can be i64, i32, f64, f32 (optional, default 'i64')
• wasm

Returns Buffer

costTable

The costTable option defines the cost of each of the operations. Cost Tables consist of an object whose keys are sections in a wasm binary. For example

module.exports = {
  'start': 1,
  'type': {
    'params': {
      'DEFAULT': 1
    },
    'return_type': {
      'DEFAULT': 1
    }
  },
  'import': 1,
  'code': {
    'locals': {
      'DEFAULT': 1
    },
    'code': {
      'DEFAULT': 1
    }
  },
  'memory': (entry) => {
    return entry.maximum * 10
  },
  'data': 5
}

Keys can either map to a function which will be given that section's entries or an integer which will be used as the cost for each entry or an object whose keys are matched against the JSON representation of the code. The default cost table used is from here

The cost table can use a special key 'DEFAULT' that will be used as the cost value for any fields in a section that are not defined.

Initial Cost

The Initial cost for instantation for the module is calculated from all the sections other than the code section (which is metered at runtime). This information is stored as a custom section that is inserted directly after the preamble. It uses the the name initCost and its payload contains the initial cost encoded as an unsigned leb128 interger.

LICENSE

MPL-2.0