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, which utilizes 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.

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'
  // }
});