https://github.com/emschwartz/codius-engine
Codius smart oracle runtime engine for Node.js
https://github.com/emschwartz/codius-engine
Last synced: 4 months ago
JSON representation
Codius smart oracle runtime engine for Node.js
- Host: GitHub
- URL: https://github.com/emschwartz/codius-engine
- Owner: emschwartz
- License: isc
- Created: 2014-07-28T18:29:19.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2015-01-14T16:37:37.000Z (over 10 years ago)
- Last Synced: 2025-02-16T10:36:22.049Z (4 months ago)
- Language: JavaScript
- Homepage:
- Size: 487 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Contracts Engine
The engine to run contracts
## Playing with the engine
+ `npm install`
+ `npm test` runs the existing tests
+ Use the [`codius-cli`](https://github.com/codius/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`](https://github.com/codius/node-sandbox), though that will soon be replaced with Native Client.
The [`Engine`](lib/engine.js) is the main component used to run contract code and the [`ContractRunner`](lib/contractrunner.js) 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`](runtime_library/) components, which are loaded into the sandbox by default.
One of the most important `runtime_library` components is [`require`](runtime_library/module.js) 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! [](https://gitter.im/codius/codius-chat)
## APIs and Message Formats
### IPC Messaging Format
#### Contract -> Sandbox
API call with callback
```js
{
"type": "api",
"api": "http",
"method": "get",
"data": "http://some.url",
"callback": 4
}
```
#### Sandbox -> Contract
API callback
```js
{
"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
```js
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.