Document get started repository for building CCF applications using (JavaScript and C++).

Steps to build network, open network, activate members, deploy app, etc.

"You would skip these steps if you use mCCF"

• Main Repo for CCF (Build apps/sub-section)

Next Steps (Nov 9th):

• Submit PR to Amaury and Takouro
• Async review PR and determine best place to put documentation (but realistically in CCF main repo)

I will create a PR on the samples repo, and after revision and acceptance we can extract the generic parts and push it to the main CCF docs.

Leverage the generic governance scripts for our skeleton app.
For the skeleton app, we can assume 1 member & 1 user for now...

1. Define config for skeleton app
2. Test adding a member, a user and proposing the skeleton app in enclave/virtual environment (not MCCF yet).

To confirm the make demo finishes with exit code 0. It will prevent bugs like #90

There may be another place in CCF that creates a set_app_js governance proposal document for us to be able to register an application in the network. So this may be unnecessary, so happy to remove this. As mentioned here, https://microsoft.github.io/CCF/main/build_apps/js_app_bundle.html#deployment we need to create set_js_app proposal.

If this is worthwhile addition I can also amend the documentation in the main CCF repository

Per demo requirements, we will need to demonstrate governance actions = a code change.

https://github.com/microsoft/ccf-app-samples/blob/main/data-reconciliation-app/demo/demo-guidance.md

[SPIKE] - Proof that version 1 of the application is still running whilst there is a active proposal (version 2)

Create a script to

1. Propose code change to network - add another field to summary object. Total Votes.
2. Members vote and approve
3. Run E2E test (ingest and report apis) - you should see the new field in the data reporting returned json

Acceptance Critera:

1. We assume that this code change will be a non-breaking change to the application

When a build of main fails (timeout) it does not delete the resource group and we then encounter quota issues

The PG have several other groups that are collaborating with CCF in the same capacity as Crew Neutrino. They are currently using AzDO, duplicating issues, over-complex collaboration model. Amaury really likes how we set up our collaboration model: separate, self-managed project, triage --> issues, and how our issues flow into their backlog.

They asked if we could document how we set up this collaboration model.

Acceptance Criteria:

1. Document and provide resources/links/demo to PG on how we set up this collaboration model within Git.

Build the Banking Application in a continuous integration so we can test the validity of any code changes

Currently there are certificates shipped with the repository for the demo in banking_app/certs_for_demo. These could be created when the demo is initiated.

Suggested by @heidihoward .
It was originally in CCF/samples/apps/forum at 7455dd869df4996d267af228d17a484a33cd67c7 · microsoft/CCF (github.com).

Maybe it doesn't highest priority, but it's worth to consider.

• Rough design (Currently there is no documentation)
• Implement
• Write doc

When the CI is triggered it should build the devcontainer and use that to run the tests - this way we know that the devcontainer always works

Context from PG/Amaury:

• Takuro will be adding 3 applications to the ccf-app-samples repository (banking app, logging app, contact discovery app)
• Build make in an extensible way for future sample applications being added
• We want to make this repo easier to use from DX example; thus, introducing make files to build + test code pointing to one app.
• Only focus on JS Samples (as C++ will be phased out)
• Keep in mind: the sample applications will ultimately be sample containerized applications with many different languages (make + docker? -- keep this in mind in make design decisions)

I have a change that I have made to the sandbox.sh in the main CCF repository. In order to get this we will have to upgrade the samples dev container. This could cause some issues as we move from 3 to 3.1.

Describe the bug
make test-docker-virtual doesn't finish if it's run in codespace.

Steps to reproduce

1. Open the repo with codespace
2. cd banking-app
3. make test-docker-virtual

Update the documents so that they "flow" better as a new developer to the repository

Based on data ingest ADR, implement and unit test data ingest APIs:

• Add a single record
• Batch add a N records

1. Code checked into ccf-app-samples

Dependent on #83

Reference these files: -

• https://github.com/Aymalla/ccf-app-samples/blob/aym/forum-app/forum/src/controllers/csv.ts
• https://github.com/Aymalla/ccf-app-samples/blob/aym/forum-app/forum/src/services/csv.ts

Acceptance Criteria

• Define an app.json for the ingestion of the data reconciliation
• Implement the API endpoint to ingest the data from CSV
• Unit Test (make unit-test)

Currently we have different scripts between docker and the sandbox.sh - We can probably do better here to open the network and then have the same files that test the application. How we start the network should be the only difference.

In the samples repo we have a config and docker folder in the root. These should be in each sample so that each sample can move at its own release cadence.

Acceptance Criteria

• All existing samples to be updated so that we have a standard across the repo

• Get the test data
• Get the demo scenarios to test

Acceptance Criteria

• When this is completed make sure that we use the same testing pattern that we have for the Banking Sample

After cloning the repository, there should be a one line command to test the sample application(s)

Context from PG/Amaury:

• Takuro will be adding 3 applications to the ccf-app-samples repository (banking app, logging app, contact discovery app)
• Build make in an extensible way for future sample applications being added
• We want to make this repo easier to use from DX example; thus, introducing make files to build + test code pointing to one app.
• Only focus on JS Samples (as C++ will be phased out)
• Keep in mind: the sample applications will ultimately be sample containerized applications with many different languages (make + docker? -- keep this in mind in make design decisions)

Initial Idea:
Fix up --no-default-constitution within prepare_demo.sh
As part of the Banking Application Sample we copy over the constitution/resolve.js so that the sandbox.sh works - is this correct - what is the correct model here?

Next Steps (Nov 9th):

• Set up knowledge transfer/brainstorming session about constitution/correct models surrounding constitutions
• It is likely this model will change (pattern will be created) based on N number of sample applications

Update after talking to Takuro
When the Banking Sample was originally created it used the constitution of the Sandbox and overrode the resolve.js. We are going to amend the Banking Sample to run the network in docker and not use sandbox.sh. We will also demonstrate the Governance stage and therefore should define the constitution. This would mean we would not use the sandbox files, but rather include all 4 js files in the Banking Sample.

Update 16th November
Q: How do we update a constitution?
A: There is an api that allows you to update the constitution. Just be aware that any outstanding proposals will be closed when a new constitution is approved.

Short term goal

• Run tests with the virtual TEE environment.

Long term goal

• Run tests with actual SGX or SEV-SNP

Tool

GitHub Actions should be enough.

We should have a simple way of building a VM in Azure and deploy the sample application to it so we can show customers how to deploy it to Azure

Feedback/Context from PG:

There is some value in this story.

• This may be useful for a developer to understand how to get a single node, CCF network app to run on Infrastructure; however, this is not how most will set up their networks in production environments

• This may also be useful to run performance testing on deployed/running sample app.

• Useful to get someone started

• In reality, SGX is not the easiest VM for any dev to create (limited to certain regions, very expensive). Suggested that we leverage any D.C Intel VM for this story.

• What may be "More Useful"and provide more value is taking a sample app CCF app here and deploying it to Azure leveraging mCCF ARM templates + documenting that workflow for a developer (more realistic use case than VM)

• Recommend we get access to mCCF first, as this ticket can provide more value once we have an idea of ARM templates/mCCF world

• Feature labels

• Bug labels

• Check in with MK so that we can slice a view by Feature/Story/Task

After cloning the repository, there should be a one line command to build the sample application(s)z

Context from PG/Amaury:

• Takuro will be adding 3 applications to the ccf-app-samples repository (banking app, logging app, contact discovery app)
• Build make in an extensible way for future sample applications being added
• We want to make this repo easier to use from DX example; thus, introducing make files to build + test code pointing to one app.
• Only focus on JS Samples (as C++ will be phased out)
• Keep in mind: the sample applications will ultimately be sample containerized applications with many different languages (make + docker? -- keep this in mind in make design decisions)

The https://github.com/microsoft/ccf-app-samples/ repository has previously had certificates stored inside it for the demo. These were replaced by dynamically creating the certificates as part of the demo.

However this means the certs are in the git history and this means it is problematic to fork this repository to Azure DevOps.

I think we should squash the commits before and after the certs being added now before we iterate further.

The current demo.sh is a mixture of calling the governance APIs and then the actually Banking Application. Split this into 2 separate scripts so that it is easier to understand.

Also add comments in the bash scripts so dev understands what each line of code does.

There is a need to define the testing strategy inside the sample

Work with Brent to determine any schema requirements (input and reporting) as well as any demo expectations.

Acceptance Criteria:

1. Add docs to repo

Our Skelton App will be a hello world app w/ API endpoint!

Set up CI to build app.

Define repository structure for /data-reconciliation-app in ccf-app-samples repo. Be sure to reference the banking-app and follow a similar structure for our app.

App structure
Reference template: https://github.com/microsoft/ccf-app-template/tree/main/js

• logging
• unit testing
• NO TSOA
  ***minimum npm packages

CCF Stuff

• Governance Scripts
• Constitution
• build_bundle.js
• rollup.config.js

Docs

• design docs
• Readme
• etc

Acceptance Criteria:

1. Design + Propose repo structure for our sample application

Design Data Reconciliation

Acceptance Criteria:

• ADR
• If pseudo code means that teh ADR needs changes than update as part of this story
• Pseudo Code document of "how" we reconcile.

Dependent on conversation with Brent

We have existing scripts for the banking-app

1. Create member + activate
2. Create user and activate
3. Submit proposal to deploy app to mCCF

Acceptance Criteria:

1. Move AzDO scripts to ccf-app-samples
2. Generalize & configure scripts - so they can be used for banking-app and data-reconciliation-app (Config file per sample app?)
3. Test generalized governance scripts on banking-app in mCCF

Based on data reporting ADR, implement and unit test data data reporting APIs:

• GET data summary on all records
• GET data summary by unique ID
• Implement reconciliation logic in this service. Returns summary object(s)

Domain Model according to this ADR

• Design
• Implement
• Test

Reference these files:

• Data reporting ADR: #85

Acceptance Criteria

• Define an app.json for the data reporting
• Implement the API endpoint to return the summary object(s) JSON
• Unit Test (make unit-test)

https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour

ccf-app-template has one for the C++ app

The banking-app-sample will have its own constitution. Update the auditable-logging-app sample to follow the same pattern

ADR to define a generalised ingest API

• REST definition with noun/verb of how we ingest the data
• consider PartitionKey and attributes

Dependent on the LEI schema investigation

Design Data Reporting - API, Service & Repository Layers.

Requirements: https://github.com/microsoft/ccf-app-samples/blob/main/data-reconciliation-app/docs/data-schema-data-flow.md#data-reporting

Members will query for report summary. All data returned will be JSON. Voting Threshold should be configurable.

Design APIs:

• by individual record (unique ID)
• for ALL data

Design Service Layer

• Design returned summary object. Table: https://github.com/microsoft/ccf-app-samples/blob/main/data-reconciliation-app/docs/data-schema-data-flow.md#data-results-schema. Summary object can be used for both APIs.
• Pseudo Code: how we will manipulate the domain model (K-V store) and create summary object?

Repository Layer:

• Query K-V store by ID
• Query K-V store for ALL

Acceptance Criteria:

1. ADR
2. Review ADR with team (Sync or Async)

After repository structure is defined, create a hello world skeleton app for our data-reconciliation scenario.

Includes:

• domain model
• API endpoint for hello world
• Unit test

Acceptance Criteria

1. Code checked into ccf-app-samples

Current Docker Image builder generates member0 certificate and keys to be used by application. For security reasons, image must not hold that information.

Change build structure to generate member0 certificate in a previous stage, and create docker image only with the relevant information needed to open the network

Next Steps (Nov 9th):

• Great idea, CCF team hasn't had time to do this yet.

Bring the banking-app implementation from https://github.com/takuro-sato/ccf-app-template/tree/example_apps .

Describe the bug
I get an error of terminating with uncaught exception of type std::logic_error: SGX enclaves are not supported in current build - cannot launch /usr/lib/ccf/libjs_generic.virtual.so when trying to run an example with the docker virtual image

Steps to reproduce
I had to update the docker file to generate the member cert in the docker image since I can't install ccf locally but I don't think that would cause such an error.

1. update banking-app/docker/ccf_app_js.virtual to generate member0 cert in docker file

diff --git a/banking-app/docker/ccf_app_js.virtual b/banking-app/docker/ccf_app_js.virtual
index 2b9d6e6..a115605 100644
--- a/banking-app/docker/ccf_app_js.virtual
+++ b/banking-app/docker/ccf_app_js.virtual
@@ -10,11 +10,12 @@ COPY --from=builder /opt/ccf_virtual/lib/libjs_generic.virtual.so /usr/lib/ccf
 # copy configuration into image
 COPY ./constitution/*.js /app/
 COPY ./config/cchost_config_virtual_js.json /app/
-COPY ./workspace/docker_certificates/member0_cert.pem /app/
-COPY ./workspace/docker_certificates/member0_enc_pubk.pem /app/
 
 WORKDIR /app/
 
+COPY --from=builder /opt/ccf_virtual/bin/keygenerator.sh /app/
+RUN /app/keygenerator.sh --name member0 --gen-enc-key
+
 EXPOSE 8080/tcp
 
 CMD ["/usr/bin/cchost", "--config", "/app/cchost_config_virtual_js.json"]

2. remove certificate generation from build_image.sh

diff --git a/build_image.sh b/build_image.sh
index 9d9b9c9..51c7ca4 100755
--- a/build_image.sh
+++ b/build_image.sh
@@ -24,9 +24,9 @@ mkdir -p $app_path/workspace/docker_certificates
 
 echo "-- generating member0 certificates"
 # This is directly related to the member described in host config file 
-cd $app_path/workspace/docker_certificates
-$ccf_prefix/keygenerator.sh --name member0 --gen-enc-key
+#cd $app_path/workspace/docker_certificates
+#$ccf_prefix/keygenerator.sh --name member0 --gen-enc-key

3. cd banking-app
4. npm install
5. make build-virtual
6. docker run banking-app:virtual

2022-12-08T19:48:25.962404Z        100 [info ] ../src/host/main.cpp:125             | CCF version: ccf-3.0.1
2022-12-08T19:48:25.962602Z        100 [info ] ../src/host/main.cpp:133             | Configuration file /app/cchost_config_virtual_js.json:
{
  "enclave": {
    "file": "/usr/lib/ccf/libjs_generic.virtual.so",
    "type": "Virtual"
  },
  "network": {
    "node_to_node_interface": {
      "bind_address": "172.17.0.3:8081"
    },
    "rpc_interfaces": {
      "main_interface": {
        "bind_address": "172.17.0.3:8080"
      }
    }
  },
  "command": {
    "type": "Start",
    "service_certificate_file": "/app/service_cert.pem",
    "start": {
      "constitution_files": [
        "/app/validate.js",
        "/app/apply.js",
        "/app/resolve.js",
        "/app/actions.js"
      ],
      "members": [
        {
          "certificate_file": "/app/member0_cert.pem",
          "encryption_public_key_file": "/app/member0_enc_pubk.pem"
        }
      ]
    }
  }
}
2022-12-08T19:48:25.962649Z        100 [info ] ../src/host/main.cpp:164             | Recovery threshold unset. Defaulting to number of initial consortium members with a public encryption key (1).
terminating with uncaught exception of type std::logic_error: SGX enclaves are not supported in current build - cannot launch /usr/lib/ccf/libjs_generic.virtual.so```

Create E2E API Test. Test Data Ingest API.

Reference how e2e tests look in forum app with fake auth
https://github.com/microsoft/CCF/blob/7455dd869df4996d267af228d17a484a33cd67c7/samples/apps/forum/test/e2e/api.test.ts

Dependent on #82

1. Code checked into ccf-app-samples

Acceptance Criteria

• Receiving a 200 OK from the ingestion API is a Pass at this point
• Works in all 3 hosting models (sandbox, container and mCCF)

At the moment, running ./banking-app/test.sh only works the first time as it relies on a bank account balance which always increases.

Update the test so that you can run it multiple times.

Research LEI data structure + data flow. After investigating if possible, create a sample data set (1 excel spreadsheet).

Acceptance Criteria

1. Design doc on data model for LEI data
2. Create 1 set of sample data for 1 member

Dependent on conversation with Brent

Install the following features in the DevContainer for ease of development

• Docker from Docker (this allows you to use the host docker engine from within the DevContainer)
• Node 16.7

Investigate how we are going to deploy an application to the managed CCF in Azure

Investigate whether there is a bicep possibility with this (escape hatches)