CCF App Template

Template repository for JavaScript and C++ CCF applications.

Quickstart

The quickest way to build and run this sample CCF app is to checkout this repository locally in its development container by clicking:

All dependencies will be automatically installed (takes ~2 mins on first checkout).

Alternatively, if your organisation supports it, you can checkout this repository in a Github codespace:

JavaScript

CCF apps can be written in JavaScript/TypeScript. This is the quickest way to develop new apps as this does not require any compilation step and the app can be updated on the fly, via a governance proposal.

The JavaScript sample bundle is located in the js/ directory.

Run JS app

$ npm --prefix ./js install
$ npm --prefix ./js run build
$ /opt/ccf/bin/sandbox.sh --js-app-bundle ./js/dist/
[12:00:00.000] Virtual mode enabled
[12:00:00.000] Starting 1 CCF node...
[12:00:00.000] Started CCF network with the following nodes:
[12:00:00.000]   Node [0] = https://127.0.0.1:8000
[12:00:00.000] You can now issue business transactions to the libjs_generic application
[12:00:00.000] Loaded JS application: ./js/dist/
[12:00:00.000] Keys and certificates have been copied to the common folder: /workspaces/ccf-app-template/workspace/sandbox_common
[12:00:00.000] See https://microsoft.github.io/CCF/main/use_apps/issue_commands.html for more information
[12:00:00.000] Press Ctrl+C to shutdown the network

In another terminal:

$ curl -X POST https://127.0.0.1:8000/app/log?id=1 --cacert ./workspace/sandbox_common/service_cert.pem -H "Content-Type: application/json" --data '{"msg": "hello world"}'
$ curl https://127.0.0.1:8000/app/log?id=1 --cacert ./workspace/sandbox_common/service_cert.pem
hello world

Docker

It is possible to build a runtime image of the JavaScript application via docker:

$ docker build -t ccf-app-template:js-enclave -f docker/ccf_app_js.enclave .
$ docker run --device /dev/sgx_enclave:/dev/sgx_enclave --device /dev/sgx_provision:/dev/sgx_provision -v /dev/sgx:/dev/sgx ccf-app-template:js-enclave
...
2022-01-01T12:00:00.000000Z -0.000 0   [info ] ../src/node/node_state.h:1790        | Network TLS connections now accepted
# It is then possible to interact with the service

Or, for the non-SGX (a.k.a. virtual) variant:

$ docker build -t ccf-app-template:js-virtual -f docker/ccf_app_js.virtual .
$ docker run ccf-app-template:virtual

C++

CCF apps can also be written in C++. This offers better performance than JavaScript apps but requires a compilation step and a restart of the CCF node for deployment.

The C++ sample app is located in the cpp/ directory.

Also check out the code tour to get an overview of the C++ app.

Build C++ app

In the checkout of this repository:

$ cd cpp/
$ mkdir build && cd build
$ CC="/opt/oe_lvi/clang-10" CXX="/opt/oe_lvi/clang++-10" cmake -GNinja ..
$ ninja
$ ls
libccf_app.enclave.so.signed # SGX-enabled application
libccf_app.virtual.so # Virtual application (i.e. insecure!)

See docs for complete instructions on how to build a CCF app.

Run C++ app

$ /opt/ccf/bin/sandbox.sh -p ./libccf_app.virtual.so
Setting up Python environment...
Python environment successfully setup
[12:00:00.000] Virtual mode enabled
[12:00:00.000] Starting 1 CCF node...
[12:00:00.000] Started CCF network with the following nodes:
[12:00:00.000]   Node [0] = https://127.0.0.1:8000
[12:00:00.000] You can now issue business transactions to the ./libccf_app.virtual.so application
[12:00:00.000] Keys and certificates have been copied to the common folder: .../ccf-app-template/build/workspace/sandbox_common
[12:00:00.000] See https://microsoft.github.io/CCF/main/use_apps/issue_commands.html for more information
[12:00:00.000] Press Ctrl+C to shutdown the network

Or, for an SGX-enabled application (unavailable in development container): $ /opt/ccf/bin/sandbox.sh -p ./libccf_app.enclave.so.signed -e release

Docker

It is possible to build a runtime image of the C++ application via docker:

$ docker build -t ccf-app-template:cpp-enclave -f docker/ccf_app_cpp.enclave .
$ docker run --device /dev/sgx_enclave:/dev/sgx_enclave --device /dev/sgx_provision:/dev/sgx_provision -v /dev/sgx:/dev/sgx ccf-app-template:cpp-enclave
...
2022-01-01T12:00:00.000000Z -0.000 0   [info ] ../src/node/node_state.h:1790        | Network TLS connections now accepted
# It is then possible to interact with the service

Or, for the non-SGX (a.k.a. virtual) variant:

$ docker build -t ccf-app-template:cpp-virtual -f docker/ccf_app_cpp.virtual .
$ docker run ccf-app-template:virtual

---

Dependencies

If this repository is checked out on a bare VM (e.g. for SGX deployments), the dependencies required to build and run the C++ app can be installed as follows:

$ wget https://github.com/microsoft/CCF/releases/download/ccf-2.0.0/ccf_2.0.7_amd64.deb
$ sudo dpkg -i ccf_2.0.7_amd64.deb # Install CCF under /opt/ccf
$ cat /opt/ccf/share/VERSION_LONG
ccf-2.0.7
$ /opt/ccf/getting_started/setup_vm/run.sh /opt/ccf/getting_started/setup_vm/app-dev.yml # Install dependencies

See the CCF official docs for more info.

Code Tour

In VSCode, a code tour of the C++ app can be started with: Ctrl + P, > CodeTour: Start Tour