Onboarding¶

This page aims to be a list of resources that should be helpful if you want to start contributing to CCF.

Introduction¶

Start by reading What is CCF?.

If you encounter any terms or acronyms that you do not know, check the Glossary. If the word you are looking for is not defined, create an issue.

Build CCF¶

First complete CCF Development Setup, and see Build CCF from Source.

Walk through a sample application¶

Example app (C++) documents the sample C++ app under /samples/apps/logging in the repo.

The logging application is simple, but exercises most features of the framework, and is extensively used in the end to end tests.

To run a locally built copy of this application in a sandbox, see Running CCF Applications. The package name will be samples/apps/logging/liblogging:

~/CCF/build$ ../tests/sandbox/sandbox.sh -p samples/apps/logging/liblogging

Setting up Python environment...
Python environment successfully setup
[11:44:33.376] Starting 1 CCF node...
[11:44:33.376] Virtual mode enabled
[11:44:35.025] Started CCF network with the following nodes:
[11:44:35.025]   Node [0] = https://127.0.0.1:8000
[11:44:35.025] You can now issue business transactions to the samples/apps/logging/liblogging application
[11:44:35.025] Keys and certificates have been copied to the common folder: /home/$USER/CCF/build/workspace/sandbox_common
[11:44:35.025] See https://microsoft.github.io/CCF/main/use_apps/issue_commands.html for more information
[11:44:35.025] Press Ctrl+C to shutdown the network

Have a look at the Continuous Integration jobs¶

The main CI job for CCF is defined in a YAML file in the repo and runs are accessible here.

That job gates pull requests, and is also used with a different trigger (on tags like ccf-*) to produce releases.

Three more in-depth jobs are run every day:

The Daily build (.daily.yml) is longer version of the CI, and makes use of instrumentation (ASAN, UBSAN…).
The Threading build (.multi-thread.yml) tests CCF with multiple worker threads.
The Stress build (.stress.yml) runs long-lived tests against CCF networks.

Documentation is built and published to GitHub Pages by this job (YAML).

Review the release and compatibility policy¶

Release and compatibility policy defines what changes are possible in CCF and what timeline they must follow.

Simplified Data Flow Map¶

This chart is a simplified illustration of the data flow in a running CCF service. Where possible, nodes and edges have been made links to the most relevant documentation page or file.

Note that this diagram deliberately does not represent host-to-enclave communication.

        flowchart TB
    Client[HTTPS/1.1 Client <a href='../build_apps/auth/index.html'>auth</a>] -- TLS 1.2 or 1.3 --> TLSSession
    TLSSession[TLS Session <a href='https://github.com/microsoft/CCF/blob/main/src/enclave/tls_session.h'>src</a>] -- PlainText --> HTTPSession
    HTTPSession[HTTP Session <a href='https://github.com/microsoft/CCF/blob/main/src/http/http_session.h'>src</a>] -- Request --> Endpoint[Application Endpoint <a href='../build_apps/api.html#application-endpoint-registration'>doc</a>]
    Endpoint -- Response --> HTTPSession
    HTTPSession --> TLSSession
    TLSSession --> Client
    Endpoint -- WriteSet --> Store[Store <a href='../build_apps/kv/index.html'>doc</a>]
    Store -- LedgerEntry --> Ledger[Ledger <a href='../architecture/ledger.html'>doc</a>]
    Ledger -- LedgerEntry --> Disk
    Store[Key-Value Store] -- Digest --> MerkleTree[Merkle Tree <a href='../architecture/merkle_tree.html'>doc</a>]
    Store -- LedgerEntry --> Consensus[Consensus <a href='../architecture/consensus/index.html'>doc</a>]
    Consensus -- Messages --> OtherNodes[Other Nodes <a href='../architecture/node_to_node.html'>doc</a>]
    OtherNodes --> Consensus
    Consensus -- Sign --> MerkleTree
    MerkleTree -- Signature --> Store

Doxygen¶

Doxygen description of the codebase is available here.