Skip to content

Latest commit

 

History

History
90 lines (60 loc) · 3.25 KB

CONTRIBUTING.md

File metadata and controls

90 lines (60 loc) · 3.25 KB
Raw

Code Conventions and Design Notes

As noted in .travis.yml, all contributions must pass npm run check, which runs test, lint, etc. The test check is conventional unit tests.

Contributions should also pass npm run integrationTest, which requires a running validator node (see below).

To run both the offline and online tests, use npm run testAll.

Static Typechecking: flow

We use flow for static typing. The npm run flow-check script does a complete check and npm run flow-status does an incremental check.

0## RChain Validator Node for Integration testing

One way to provide a validator node for testing, provided you're OK with the security risks around --net host, is to first have the node start up and generate some random validator keys:

docker run --rm --net host -v$HOME/.rnode:/var/lib/rnode \
    rchain/rnode run -s

Then grab one of the secret keys for use as a validator private key:

first_key=$(cat $(ls ~/.rnode/genesis/*.sk|head -1))

docker run --rm --net host -v$HOME/.rnode:/var/lib/rnode \
    rchain/rnode run -s --validator-private-key $first_key

Code Style: airbnb

We follow the Airbnb JavaScript Style Guide, mostly. Use npm run lint. See .eslitrc.json for additional details.

Object capability (ocap) discipline

In order to supporting robust composition and cooperation without vulnerability, code in this project should adhere to object capability discipline.

  • Memory safety and encapsulation

    • There is no way to get a reference to an object except by creating one or being given one at creation or via a message; no casting integers to pointers, for example. JavaScript is safe in this way.

      From outside an object, there is no way to access the internal state of the object without the object's consent (where consent is expressed by responding to messages). We use def (aka Object.freeze) and closures rather than properties on this to achieve this.

  • Primitive effects only via references

    • The only way an object can affect the world outside itself is via references to other objects. All primitives for interacting with the external world are embodied by primitive objects and anything globally accessible is immutable data. There must be no open(filename) function in the global namespace, nor may such a function be imported. It takes some discipline to use modules in node.js in this way. We use a convention of only accessing ambient authority inside if (require.main == module) { ... }.

Protobuf Encoding: protobuf.js

All of our protobuf encoding and decoding is done using protobuf.js

protobuf.js diagram

Extracting API doc

We use documentation.js to build API docs (docs/index.md) from sources. Use the docs-watch, build:docs, or build:docs-html npm scripts.