tdfischer / codius-engine

Codius smart oracle runtime engine for Node.js

Contracts Engine

The engine to run contracts

Playing with the engine

• npm install
• npm test runs the existing tests
• Use the codius-cli to run test contracts

Structure of the engine

The engine is the part of Codius responsible for running sandboxed code and providing APIs for that code to communicate with.

For the sandbox we are currently using codius/node-sandbox, though that will soon be replaced with Native Client.

The Engine is the main component used to run contract code and the ContractRunner is responsible for handling messages coming from the sandbox and passing valid ones to the corresponding APIs.

Contract code uses the postMessage command to communicate with the outside. The format is defined below. Most contracts will not use the postMessage command directly but will instead use modules or runtime_library components, which are loaded into the sandbox by default.

One of the most important runtime_library components is require which loads modules, Javascript, and JSON files akin to Node.js's require. require's behavior is also outlined below.

Questions?

Any questions? Join the live chat!

APIs and Message Formats

IPC Messaging Format

Contract -> Sandbox

API call with callback

{
  "type": "api",
  "api": "http",
  "method": "get",
  "data": "http://some.url",
  "callback": 4
}

Sandbox -> Contract

API callback

{
  "type": "callback",
  "callback": 4,
  "error": null,
  "result": "some stringified result"
}

Contract-specific Secrets and Keypairs

Secret Derivation

The engine must be started with a MASTER_SECRET.

This secret is used to derive multiple other secrets, which are used to provide contracts with unique private values and public/private key pairs. Derived secrets are the HMAC of the "parent" secret and the name of the "child" secret

• CONTRACT_SECRET_GENERATOR - used to generate 512-bit private values
• CONTRACT_KEYPAIR_GENERATOR_ec_secp256k1 - used to generate secp256k1 key pairs (e.g. CONTRACT_KEYPAIR_13550350a8681c84c861aac2e5b440161c2b33a3e4f302ac680ca5b686de48de)
• other CONTRACT_KEYPAIR_GENERATOR_{other signature schemes} (e.g. ec_ed25519)
• MASTER_KEYPAIR_ec_secp256k1 - used to sign contracts' public keys
• other MASTER_KEYPAIR_{other signature schemes} (e.g. ec_ed25519)

API

var secrets = require('secrets');

// Get a secret that is deterministically generated and unique for the contract
secrets.getSecret(function(error, secret){
  // error: null
  // secret: "c88097bb32531bd14fc0c4e8afbdb8aa22d4d6eefcbe980d8c52bd6381c6c60ca746b330ce93decf5061a011ed71afde8b4ed4fbbf1531d010788e8bb79c8b6d"
});

// Get a secp256k1 key pair and the engine's signature on the public key
// Note that the signature is in DER format
secrets.getKeypair('ec_secp256k1', function(error, keypair){
  // error: null
  // keypair: {
  //   public: '0417b9f5b3ba8d550f19fdfb5233818cd27d19aaea029b667f547f5918c307ed3b1ee32e285f9152d61c2a85b275f1b27d955c2b59a313900c4006377afa538370',
  //   private: '9e623166ac44d4e75fa842f3443485b9c8380551132a8ffaa898b5c93bb18b7d',
  //   signature: '304402206f1c9e05bc2ad120e0bb58ff368035359d40597ef034509a7dc66a79d4648bea022015b417401d194cf2917e853a7565cfbce32ee90c5c8f34f54075ee2f87519d88'
  // }
});

Require

require can be used in the sandbox to load modules, javascript files, and JSON files.

The following table explains how require will interpret paths:

Given path	File returned
module_name	main file identified in codius_modules/module_name/codius-manifest.json
./file.js or ./file	./file.js or file.js listed in the files of the current context's manifest
./file.json	./file.json or file.json listed in the files of the current context's manifest
./codius_modules/module_name/file.js or module_name/file.js	./file.js or file.js listed in the files of module_name's manifest
./directory	main file identified in ./directory/codius-manifest.json or ./directory/package.json, or ./directory/index.js
../file.js	./file.js or file.js from the parent directory or parent module of the current context

* Note that absolute paths (e.g. /codius_modules/module_name/file.js) are not currently supported.