SolMATe - The Solidity Matrix Environment

SolMATe is the fundamental package for floating-point math, array manipulation, and linear algebra in Ethereum smart contracts. With SolMATe you get:

Gas-efficient operations with signed 59.18-decimal fixed-point numbers
Functions for manipulating vectors and matrices
Linear algebra routines enabling the implementation of machine learning algorithms, such as multivariate linear regression and deep neural networks

SolMATe is the first-ever package making it possible to engage in all aspects of a machine learning pipeline directly on the blockchain - from data collection to model training and evaluation - without having to involve an off-chain oracle. See below for an example of a key ML algorithm (multiple linear regression) implemented as a smart contract.

Usage

The following smart contract performs multiple linear regression solving the equation Ax=b, where A is a matrix of coefficients, b is a vector of outputs, and x is the solution vector. It uses approximately 8e7 gas - making it impractical for Layer 1 applications but practical for Layer 2 as of 2022.

// SPDX-License-Identifier: BSD-4-Clause
pragma solidity >=0.8.4;
import "prb-math/contracts/PRBMathSD59x18.sol";
import "./VectorUtils.sol";
import "./MatrixUtils.sol";

contract SolMATe_demo {
    using PRBMathSD59x18 for int256;
    using VectorUtils for int256[];
    using MatrixUtils for int256[][];

    function multipleLinearRegression(int256[][] memory a, int256[] memory b) public pure returns (int256[][] memory) {
        int256[][] memory q;
        int256[][] memory r;
        int256[][] memory b_mat = b.convertTo59x18().toMatrix();
        (q,r) = a.convertTo59x18().QRDecomposition();
        return r.backSubstitute(q.T().dot(b_mat));
    }
}

We can then run the contract using the following Hardhat script:

// We require the Hardhat Runtime Environment explicitly here. This is optional
// but useful for running the script in a standalone fashion through `node <script>`.
//
// When running the script with `npx hardhat run <script>` you'll find the Hardhat
// Runtime Environment's members available in the global scope.
const hre = require("hardhat");

async function main() {
  // Hardhat always runs the compile task when running scripts with its command
  // line interface.
  //
  // If this script is run directly using `node` you may want to call compile
  // manually to make sure everything is compiled
  // await hre.run('compile');

  const SolMATe_demo = await hre.ethers.getContractFactory("SolMATe_demo");
  const solmate_demo = await SolMATe_demo.deploy();

  await solmate_demo.deployed();
  const inputMat = [[43,1],[21,1],[25,1],[42,1],[57,1],[59,1]]
  const b = [99,65,79,75,87,81]
  const result = await solmate_demo.multipleLinearRegression(inputMat, b);
  console.log(result);
}

// We recommend this pattern to be able to use async/await everywhere
// and properly handle errors.
main()
  .then(() => process.exit(0))
  .catch((error) => {
    console.error(error);
    process.exit(1);
  });

In SolMATe, all fixed point numbers are scaled by 1e18 and stored as int256 data. Importing the PRBMathSD59x18 package allows one to perform math operations on these numbers.

using PRBMathSD59x18 for int256;
int256 a = 1.5e18; // represents a = 1.5
int256 b = 2e18; // represents b = 2
a.mul(b);  // returns 3e18, or 3000000000000000000, which represents 3

Contributing

SolMATe uses Hardhat for scripts and unit testing. Pull requests are welcome - especially those pertaining to documentation, optimizing algorithms, and developing test cases.

NTA-Capital/SolMATe

SolMATe - The Solidity Matrix Environment

Usage

Contributing