web3c2.0.5 • Public • Published
Installation / Usage
web3c.js in your project, require web3c within your webpack project, or
attach the confidentiality extension onto your existing use of Web3.
$ npm install --save web3c
For convenience, we automatically build the latest version of the library here: https://cdn.oasiscloud.io/web3c-latest/web3c.js
Creating a new Web3c Project
You can either include a script tag linking the web3c library as you would a
dependency on web3, or use the library
require statement in either your Node or webpack project. Web3
will be automatically required by web3c in these cases and the wrapper can be
used in place of web3.
Constructing a Web3c Object
Constructing a Web3c object can be done in the same way as a Web3 object, with some additional options. For example,
const Web3c = ;let web3c = provider Web3keyManagerPublicKey;
The first argument,
provider, is a standard Web3 provider. The last two arguments
are optional and in most cases shouldn't be used at all unless you know what you're
doing and want to customize Web3c. Of the arguments,
Web3 is an override for
the underlying Web3 library to use, and the last object is a set of options to use.
Here one can specify the public key of the remote key manager to use.
Extending an existing Web3 project
If your dapp / project already has a web3 library, you can include the web3c library in addition, and it will wrap around the existing web3 instance. Our build defines web3 as an optional dependency, and the web3c library will not depend upon the vendored web3 unless no web3 context is present in the environment into which it is included.
If you want to convert an existing contract to confidential, you will change
the call from
new web3.eth.Contract to
new web3.oasis.Contract. If your
project interacts with an already deployed contract, you should add the key
of the confidential contract as an additional option to this call to ensure
let myContractInstance = abi deployed_addresskey: "0x59e35409ffdb0be6a74acc88d5e99e2b50782662fa5bf834b8b9d53bc59c7c4a";
If the contract is deployed as part of your project, web3c will retrieve the longterm key when the contract is deployed, and will attempt to store it for subsequent uses automatically.
Building / Development
The web3c library build uses webpack,
and can be initiated by npm. Compile with
npm run-script build, or
develop interactively with
npm run-script watch.
Tests are run by CI, ensuring that the library is in a state the builds, that
all tests pass, and that the code passes a lint check. These tests can be
run locally with
npm test. An additional set of browser integration tests
are run manually before releases to ensure functionality on the range of
expected environments. These can be run via the command
npm run-script test:browser.
Web3c is structured with a "soft" dependency on web3. This means that a default compilation of a project requiring web3c with webpack will not have web3 loaded synchronously. This choice adds a bit of complexity you should be aware of, but is useful because it allows your project to load faster and never trigger the full download of web3 in cases where the injected wallet in the user's browser already contains a copy.
There are two recommeded strategies for handling loading of web3c in a webpack project:
- Synchronous web3 You can make sure the web3 dependency ends up in the same webpack code module by including it as a direct dependnecy:
const web3c = ;; // eslint-disable-line no-unused-expressions
Note: You don't need to use web3, as all of its methods are accessible through the
web3c object. Adding a
require call somewhere in your project is a simple way
to pull the dependent code into the same code module for synchronous use.
- Asynchronous web3 You can defer usage of web3c until web3 is available:
const web3c = ;...web3cPromise;