From 9add091432124291f4700029a82f7d6cc607899b Mon Sep 17 00:00:00 2001 From: Jonathan Hamilton <33758641+jonathan-m-hamilton@users.noreply.github.com> Date: Sun, 17 Nov 2019 12:41:42 -0600 Subject: [PATCH] Documentation Housekeeping (#51) * Add Code of Conduct per #18 Signed-off-by: Jonathan Hamilton * Creating Issue templates Signed-off-by: Jonathan Hamilton * Clear historical readme info and provide new links for Rocketchat, issue templates, issue filters Signed-off-by: Jonathan Hamilton * docs(bug_report): adds more questions about env Signed-off-by: Peter Somogyvari --- .github/ISSUE_TEMPLATE/bug_report.md | 67 +++++ .github/ISSUE_TEMPLATE/feature_request.md | 20 ++ .github/ISSUE_TEMPLATE/user-story-template.md | 18 ++ CODE-OF-CONDUCT.md | 4 + README.md | 267 ++---------------- 5 files changed, 130 insertions(+), 246 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/ISSUE_TEMPLATE/user-story-template.md create mode 100644 CODE-OF-CONDUCT.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000000..ad8216ff68 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,67 @@ +--- +name: Bug report +about: Create a report to help us improve +title: '' +labels: bug +assignees: '' + +--- + +**Describe the bug** + +A clear and concise description of what the bug is. + +**To Reproduce** + +Steps to reproduce the behavior on a successfully deployed BIF cluster. + +**Expected behavior** + +A clear and concise description of what you expected to happen. + +**Logs/Stack traces** + +Can help maintainers identify root causes + +**Screenshots** + +If applicable, add screenshots to help explain your problem. + +**Cloud provider or hardware configuration:** +Are you running the software on a dev machine or somewhere in the cloud? + +**Operating system name, version, build:** + +Use this command: `printf "$(uname -srm)\n$(cat /etc/os-release)\n"` + +For example + +```sh +$ printf "$(uname -srm)\n$(cat /etc/os-release)\n" +Linux 4.15.0-70-generic x86_64 +NAME="Ubuntu" +VERSION="18.04.3 LTS (Bionic Beaver)" +ID=ubuntu +ID_LIKE=debian +PRETTY_NAME="Ubuntu 18.04.3 LTS" +VERSION_ID="18.04" +HOME_URL="https://www.ubuntu.com/" +SUPPORT_URL="https://help.ubuntu.com/" +BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/" +PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy" +VERSION_CODENAME=bionic +UBUNTU_CODENAME=bionic +``` + +**BIF release version or commit (git rev-parse --short HEAD):** + +Either a semantic version of the release you are using such as `1.0.0` or a git +commit hash if you are directly working with code from the git repository. + +**BIF Plugins/Connectors Used** + + - Which DLT connectors are you using (Fabric, Quorum, Corda, Besu, etc.) + +**Additional context** + +Add any other context about the problem here. \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000000..6532412f54 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,20 @@ +--- +name: Feature request +about: Suggest an idea for this project +title: '' +labels: enhancement +assignees: '' + +--- + +**Is your feature request related to a problem? Please describe.** +A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + +**Describe the solution you'd like** +A clear and concise description of what you want to happen. + +**Describe alternatives you've considered** +A clear and concise description of any alternative solutions or features you've considered. + +**Additional context** +Add any other context or screenshots about the feature request here. \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/user-story-template.md b/.github/ISSUE_TEMPLATE/user-story-template.md new file mode 100644 index 0000000000..3b35620671 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/user-story-template.md @@ -0,0 +1,18 @@ +--- +name: User Story template +about: Create a user story for BAF +title: '' +labels: '' +assignees: '' + +--- + +### Description +As a ... I want to ... so that .... + +(add more description and relevant links) + +### Acceptance Criteria +1. First acceptance criteria +2. ... +3. ... \ No newline at end of file diff --git a/CODE-OF-CONDUCT.md b/CODE-OF-CONDUCT.md new file mode 100644 index 0000000000..a093d40ac3 --- /dev/null +++ b/CODE-OF-CONDUCT.md @@ -0,0 +1,4 @@ +Code of Conduct Guidelines +========================== + +Please review the Hyperledger [Code of Conduct](https://wiki.hyperledger.org/community/hyperledger-project-code-of-conduct) before participating and abide by these community standards. \ No newline at end of file diff --git a/README.md b/README.md index 12c55fd157..02a944d3ff 100644 --- a/README.md +++ b/README.md @@ -11,27 +11,10 @@ - [Design Principles](#design-principles) - [How It Works](#how-it-works) - [Future Work](#future-work) +- [Contact](#contact) +- [Contributing](#contributing) - [Initial Committers](#initial-committers) - [Sponsor](#sponsor) -- [Original README](#original-readme) - - [Transfer validator](#transfer-validator) - - [Who should be a validator?](#who-should-be-a-validator) - - [How many validators should be deployed?](#how-many-validators-should-be-deployed) - - [Role & Services](#role--services) - - [Motivations](#motivations) - - [Export & Import](#export--import) - - [Export](#export) - - [Import](#import) - - [Simple Asset Transfer](#simple-asset-transfer) - - [Plugins](#plugins) - - [On-chain Logic](#on-chain-logic) - - [Connector](#connector) - - [Future Work](#future-work-1) - - [Interoperability Use Cases](#interoperability-use-cases) - - [Identity System](#identity-system) - - [Confidential Federation](#confidential-federation) - - [More plugins](#more-plugins) - - [Contributors (unsigned commits could not be included in the lab repo)](#contributors-unsigned-commits-could-not-be-included-in-the-lab-repo) ## Lab Name @@ -73,240 +56,32 @@ Blockchain Integration Framework introduces an “interoperability validator” - Implement confidential communication within the overlay network. The validator network should match the confidentiality setup of the local ledger - Replace current signature scheme by BLS to optimize the proof size (Hyperledger Ursa is a lead) -## Initial Committers - -- [tkuhrt](https://github.com/tkuhrt) -- [jonathan-m-hamilton](https://github.com/jonathan-m-hamilton) -- [petermetz](https://github.com/petermetz) -- [hugo-borne](https://github.com/hugo-borne) - -## Sponsor - -[Hart Montgomery](mailto:hmontgomery@us.fujitsu.com) ([hartm](https://github.com/hartm)) - TSC member - -To generate the full documentation in html format (in root folder): ``npm i && npm run docs`` - -Therefore, links in markdown documentation will be broken / not working. - -## Original README - -> A connector-less approach to the non-fungible asset interoperability problem in permissionned distributed ledgers - -Federation for Interop provides for data transfer across different permissioned -distributed ledgers without connectors or middleman. -Federation for Interop aims to be as plugable as possible -to existing distributed ledger infrastructure and networks. -The implementation and design of the project enables interoperability -by extending pre-existing roles and services within the existing -consensus mechanism and governance roles to limit the creation -of new entities dedicated to interoperability. - -Federation for Interop does not describe a standard -for interoperability but rather implement an architecture of roles, -services and mechanisms that serves this purpose. -Rather than relying on strict protocols, -Federation for Interop specifies minimum requirements to ensure -the cross-distributed ledger data transfer where participants can define -rules and protocols on the data they are sharing on a case-to-case basis. - -This document will provide a quick overview of: - -- [Transfer validator role](#transfer-validator) -- [Export & Import mechanism](#export-import) -- [Simple asset transfer example](#simple-asset-transfer) -- [Blockchain plugins](#plugins) -- [Future work](#future-work) - -If you prefer to get started right away: [simple asset transfer setup](../tutorials/simple-asset-transfer.md) - -### Transfer validator - -Federation for Interop introduces the ‘transfer validator’ role. -A transfer validator is a distributed ledger participant who may take -specific actions in the transfer mechanisms and provide certain services -to the other participants of the distributed ledger. -The identity of the transfer validators plays an important role in -the cohesion of the broader ecosystem -Multiple distributed ledgers -willing to interact with each other, since they represent -their local distributed ledger from an external point of view. - -#### Who should be a validator? - -Validators are participants chosen by -the local distributed ledger governance system, -their number will vary from one distributed ledger to the other based on needs. -Potential transfer validators are easy to -identify in private and/or permissioned ledgers: -they will match existing identifiable participants in the distributed network -such as participants taking part in the consensus mechanism or in the governance. -Any well-known participant, within and outside the local distributed ledger, -is a good potential candidate. - -#### How many validators should be deployed? - -Typically, there is a substantial number of -transfer validators within each distributed ledger. -The ideal setup is to have enough transfer validators to avoid intentional, -arbitrary or induced denial of service. Depending on the ecosystem, -this number may vary from a few nodes to the entire network. - -#### Role & Services - -Each transfer validator exposes one or multiple public keys that -are attached to its identity in the distributed ledger, -as well as a service of certification. Any participant of the network, -validators included can ask a validator to certify a -piece of information coming from the local distributed ledger -according to specific known lower-level protocol. On a case-to-case basis, -validator will ever grant the certification in -the form of digital signature or reject the request. -The reason for rejection from a validator can be -multiple and internal to this validator alone -(e.g. a specific piece of information should not be disclosed -outside of the distributed ledger for confidentiality reasons). - -#### Motivations - -The transfer validators are, so to speak, the representatives of -the distributed ledger in the broader ecosystem and should make sure that -only proper information is certified to be exported -to foreign entities or distributed ledgers. While adding a new role and services -to the existing distributed ledger network, the idea is -to stay as close as possible to the existing trust model -of each distributed ledger ecosystem. Each of the components of -the transfer validator is plugeable to already running networks -and should not disrupt the inner working of distributed ledgers. - -### Export & Import +## Contact +We welcome your questions & feedback on our [Rocketchat channel](https://chat.hyperledger.org/channel/blockchain-integration-framework). -#### Export +## Contributing +We welcome contributions to BIF in many forms, and there’s always plenty to do! -Each transfer validator exposes one or more public key to be identifiable -in its local network and beyond. The core functionality of -the transfer validators is to provide a certification service -to all other participants of the local network. -The transfer validator may certify that a piece of information exists -in the local distributed ledger at a certain point in time. -The certificate consists, at minima, of the piece of information -to certify as stored in the distributed ledger as well as -a digital signature of this piece of information matching one of -the transfer validator’s public keys. A participant may collect -as many certifications as needed for a specific piece of information. -A minimal quorum of certifications is typically defined by the local ledger to -distinguish valid proofs from invalid one. The number of certification needed -for a certain proof can differ depending on the proof type. +First things first, please review the [Hyperledger Code of Conduct](https://wiki.hyperledger.org/display/HYP/Hyperledger+Code+of+Conduct) before participating. -The export mechanism relies mainly on -the ability of the validator to certify information. -The data structure and protocol used to verify the state of the local ledger -can be implemented based on the local rules of the ledger. -For example, proving that a certain asset is 'owned' by a specific -Blockchain participant may be implemented differently -depending on the technology and existing custom logic on the ledger. -See [how to extend the verification logic](../tutorials/data-check.md) for more information. +There are many ways to contibute to BIF, both as a user and as a developer. -We plan to implement high-level data protocol to cover the main interoperability -use cases (proof of ownership, asset transfer...). -See [the future work section](#future-work) for more information. +As a user, this can inlcude: +* [Making Feature/Enhancement Proposals](https://github.com/hyperledger-labs/blockchain-integration-framework/issues/new?assignees=&labels=enhancement&template=feature_request.md&title=) +* [Reporting bugs](https://github.com/hyperledger-labs/blockchain-integration-framework/issues/new?assignees=&labels=bug&template=bug_report.md&title=) -#### Import +As a developer: +* if you only have a little time, consider picking up a [“help-wanted”](https://github.com/hyperledger-labs/blockchain-integration-framework/labels/help%20wanted) or ["good-first-issue"](https://github.com/hyperledger-labs/blockchain-integration-framework/labels/good%20first%20issue) task +* If you can commit to full-time development, then please contact us on our [Rocketchat channel](https://chat.hyperledger.org/channel/blockchain-integration-framework) to work through logistics! -Messages certified by a distributed ledger’s transfer validators can be -delivered to one or multiple recipients by any secure off-chain communication system. -For instance, a certified message could be sent by email -to a foreign distributed ledger’s participant. -Entities receiving messages coming from a foreign distributed ledger of -the broader ecosystem can gather and record the transfer validator’s public key -of the emitting distributed ledger. The identity management problem is not -yet covered by the solution, see [the future work section](#future-work) for more information. -At this point, we assume that transfer validator’s public keys are -known and accessible in the broader ecosystem. - -A proof coming from a foreign distributed ledger can be verified against -the public keys the transfer validators of that foreign distributed ledger. -The number of certification needed to consider the proof as valid -within the local ledger can be defined locally or more broadly -and can depend on the type of proof, the provenance of the proof or the requestor. -Typically these elements will be decided by the governance system of the receiving ledger. - -The verification can be made by any entity that knows -the identities of the certificating validators. -If the receiving entity is a distributed ledger, the requestor may want to -trigger action on the ledger based on the verification of a valid foreign proof. -To impact the state of the local ledger and verify the proof -in a distributed manner, a separate on-chain logic on the receiving -distributed ledger can enable the sharing and distributed verifications -of any certified messages coming from registered foreign distributed ledgers. -See [the JPM Quorum plugin](#quorum-plugin) and -[Hyperledger Fabric plugin](#fabric-plugin) for more information. - -### Simple Asset Transfer - -See [simple asset transfer setup](../tutorials/simple-asset-transfer.md) for more information. - -### Plugins - -The Fabric plugin is two-fold and includes both logic to connect -to the Blockchain and smart contract extensions. - -#### On-chain Logic - -Plugin contains two on-chain logic pieces to enable imports in distributed ledgers: - -- Foreign Validator identity and public key management -- Foreign proof verification against stored identities - -See [Fabric on-chain documentation](../../examples/simple-asset-transfer/fabric/contracts/README.md) -and [Quorum on-chain documentation](../../examples/simple-asset-transfer/quorum/contracts/README.md) -for more information. Note: contracts are located under the example folder for now. - -#### Connector - -The connector class is an helper component defining how to communicate with the local Blockchain. -The connectors point to two different part of the on-chain logic: - -- Import logic: foreign validator identity and proof verification (see above) -- Base logic: custom logic of the local ledger (see [the example](../tutorials/simple-asset-transfer.md)). - Plugin connectors are using the provided Fabric SDK and a custom Quorum API, - they can be modified and extended to perfectly fit the use case - and integration layers of the local ledger, - see [how to extend connectors](../tutorials/connector.md) for more information. - -### Future Work - -#### Interoperability Use Cases - -As it stands we can prove that something happened on a foreign distributed ledger. -For more complex interoperability use cases (e.g. asset transfer, atomic swap, asset synchronization, …), -we want data protocols defining the steps and verifications needed from the validators. - -#### Identity System - -Validator identity verification is at the backbone of the solution. -We want ecosystems to be able to discover foreign validators and -store their identity in a reliable way. -Potential lead: Distributed ledger for identity (Indy, Sovrin, …) - -#### Confidential Federation - -Communication between validators is based on broadcasting. -We want the validator network to understand and -match the confidentiality setup of the local ledger. - -#### More plugins +## Initial Committers -We want to implement plugins and on-chain logic for more platforms (e.g. Digital Asset, Corda …). +- [tkuhrt](https://github.com/tkuhrt) +- [jonathan-m-hamilton](https://github.com/jonathan-m-hamilton) +- [petermetz](https://github.com/petermetz) +- [hugo-borne](https://github.com/hugo-borne) -### Contributors (unsigned commits could not be included in the lab repo) +## Sponsor - 89 hugo borne-pons - 25 denis glotov - 38 mykhailo lonin - 15 vladimir agekin - 12 naima hamouma - 5 valerijs kurme - 3 mihails gulajevs - 2 dimitrijs rulovs - 2 unknown - 1 peter somogyvari +[Hart Montgomery](mailto:hmontgomery@us.fujitsu.com) ([hartm](https://github.com/hartm)) - TSC member