diff --git a/whitepaper/.gitignore b/whitepaper/.gitignore deleted file mode 100644 index d16386367f..0000000000 --- a/whitepaper/.gitignore +++ /dev/null @@ -1 +0,0 @@ -build/ \ No newline at end of file diff --git a/whitepaper/2023_logo_hyperledger.png b/whitepaper/2023_logo_hyperledger.png new file mode 100644 index 0000000000..e6b2a6f4db Binary files /dev/null and b/whitepaper/2023_logo_hyperledger.png differ diff --git a/whitepaper/2023_logo_hyperledger.svg b/whitepaper/2023_logo_hyperledger.svg new file mode 100644 index 0000000000..221a1322d9 --- /dev/null +++ b/whitepaper/2023_logo_hyperledger.svg @@ -0,0 +1,34 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/whitepaper/Dockerfile b/whitepaper/Dockerfile deleted file mode 100644 index f3e5197217..0000000000 --- a/whitepaper/Dockerfile +++ /dev/null @@ -1,27 +0,0 @@ -FROM pandoc/latex:2.19 - -RUN tlmgr list - -RUN tlmgr update --self && \ - tlmgr install \ - enumitem \ - merriweather \ - fontaxes \ - mweights \ - mdframed \ - needspace \ - sourcesanspro \ - sourcecodepro \ - titling \ - ly1 \ - pagecolor \ - adjustbox \ - collectbox \ - titlesec \ - fvextra \ - pdftexcmds \ - footnotebackref \ - zref \ - fontawesome5 \ - footmisc \ - sectsty diff --git a/whitepaper/Makefile b/whitepaper/Makefile deleted file mode 100644 index 7f0a142292..0000000000 --- a/whitepaper/Makefile +++ /dev/null @@ -1,37 +0,0 @@ - -CURRENT_UID := $(shell id -u) -CURRENT_GID := $(shell id -g) -MAKEFILE_DIR:=$(shell dirname $(realpath $(firstword $(MAKEFILE_LIST)))) -WKFLAGS = --log-level info --dpi 150 --disable-smart-shrinking -WKMARGINS = --margin-bottom 1mm --margin-top 1mm --margin-left 1mm --margin-right 1mm - - -.PHONY: all -all: clean configure pdf - - -.PHONY: clean -clean: - rm -rf $(MAKEFILE_DIR)/build/* - -.PHONY: pdf -pdf: html pdf-wk-with-flags pdf-wk-no-flags pdf-pandoc - -.PHONY: pdf-wk-no-flags -pdf-wk-no-flags: - docker run --rm --volume $(MAKEFILE_DIR):/whitepaper --user ${CURRENT_UID}:${CURRENT_UID} --workdir /whitepaper/ --entrypoint wkhtmltopdf icalialabs/wkhtmltopdf --allow /whitepaper $(WKMARGINS) /whitepaper/build/hyperledger-cactus-whitepaper.html - /whitepaper/build/hyperledger-cactus-whitepaper-wk-no-flags.pdf - -.PHONY: pdf-wk-with-flags -pdf-wk-with-flags: - docker run --rm --volume $(MAKEFILE_DIR):/whitepaper --user ${CURRENT_UID}:${CURRENT_UID} --workdir /whitepaper/ --entrypoint wkhtmltopdf icalialabs/wkhtmltopdf --allow /whitepaper $(WKMARGINS) $(WKFLAGS) /whitepaper/build/hyperledger-cactus-whitepaper.html - /whitepaper/build/hyperledger-cactus-whitepaper-wk-with-flags.pdf - -.PHONY: pdf-pandoc -pdf-pandoc: - docker run --rm --volume $(MAKEFILE_DIR):/whitepaper --user ${CURRENT_UID}:${CURRENT_UID} --workdir /whitepaper/ petermetz/cactus-whitepaper-builder:2021-03-22-fix-703 -H deeplists.tex -V geometry:margin=1cm --standalone --output /whitepaper/build/hyperledger-cactus-whitepaper-pandoc.pdf /whitepaper/whitepaper.md - -.PHONY: html -html: - docker run --rm --volume $(MAKEFILE_DIR):/whitepaper --user ${CURRENT_UID}:${CURRENT_UID} --workdir /whitepaper petermetz/cactus-whitepaper-builder:2021-03-22-fix-703 --verbose -V fontsize=12pt -V geometry:margin=1cm -H pandoc.css --from=gfm --standalone --self-contained --to=html --metadata title="" --output=build/hyperledger-cactus-whitepaper.html --to=html /whitepaper/whitepaper.md - -configure: - docker build $(MAKEFILE_DIR) -t cactus-whitepaper-builder diff --git a/whitepaper/architecture-with-plugin-and-routing.png b/whitepaper/architecture-with-plugin-and-routing.png deleted file mode 100644 index ffe4949a69..0000000000 Binary files a/whitepaper/architecture-with-plugin-and-routing.png and /dev/null differ diff --git a/whitepaper/architecture-with-plugin-and-routing.pptx b/whitepaper/architecture-with-plugin-and-routing.pptx deleted file mode 100644 index 3752f08c8e..0000000000 Binary files a/whitepaper/architecture-with-plugin-and-routing.pptx and /dev/null differ diff --git a/whitepaper/atomic_swap.png b/whitepaper/atomic_swap.png deleted file mode 100644 index 180217b34a..0000000000 Binary files a/whitepaper/atomic_swap.png and /dev/null differ diff --git a/whitepaper/atomic_swap.pptx b/whitepaper/atomic_swap.pptx deleted file mode 100644 index b641e0bc27..0000000000 Binary files a/whitepaper/atomic_swap.pptx and /dev/null differ diff --git a/whitepaper/authorizationPermissionedChains.png b/whitepaper/authorizationPermissionedChains.png deleted file mode 100644 index 5a01280411..0000000000 Binary files a/whitepaper/authorizationPermissionedChains.png and /dev/null differ diff --git a/whitepaper/cactus_arch.svg b/whitepaper/cactus_arch.svg deleted file mode 100644 index 4346ea7419..0000000000 --- a/whitepaper/cactus_arch.svg +++ /dev/null @@ -1,2026 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - image/svg+xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Synchronous Req. - Synchronous Res. - Async Message - - - - - - - - - - - - - - - - - - Admin API - - Service API - - - Verifier - - Verifierfactory - - - LedgerEventListener - Business Logic Pluginimplementation - - ValidatorAPI - - Ledgerconnectorimpl. - - Servercontroller - - - ValidatorAPI - - Ledgerconnectorimpl. - - - - - - - - - - - - - - - - - - - Trade Context - End UserApplication - Service ProviderApplication - - - CACTUS Node Server - - - Validator server(s) - - interface - - plugin-1 - - plugin-N - - - - Legend - Validator'sKey - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Validator'sKey DB - Validatorregistry - - - - - - - - Async comm. - Synchronous comm. - - - diff --git a/whitepaper/cactus_overview.png b/whitepaper/cactus_overview.png deleted file mode 100644 index 5c8b86d283..0000000000 Binary files a/whitepaper/cactus_overview.png and /dev/null differ diff --git a/whitepaper/cactus_overview.pptx b/whitepaper/cactus_overview.pptx deleted file mode 100644 index 1ac6e3482f..0000000000 Binary files a/whitepaper/cactus_overview.pptx and /dev/null differ diff --git a/whitepaper/client-side-transaction-signing-deployment-diagram.puml b/whitepaper/client-side-transaction-signing-deployment-diagram.puml deleted file mode 100644 index be4fb1923c..0000000000 --- a/whitepaper/client-side-transaction-signing-deployment-diagram.puml +++ /dev/null @@ -1,37 +0,0 @@ - -@startuml Client Side Transaction Signing - -!include -!include -!include -!include -!include -!include - -title Hyperledger Cactus\nClient Side Transaction Signing - -left to right direction -' allow_mixing -skinparam DefaultTextAlignment center -skinparam Linetype ortho -skinparam sequenceArrowThickness 2 -skinparam roundcorner 5 -skinparam maxmessagesize 30 -skinparam sequenceParticipant underline - -actor "Application User" as actor1 <> - -FA_MOBILE(mobiledevice,"Mobile Device\n<&key>") -note bottom of mobiledevice #LightSkyBlue - <&key> Private key resides on client device of user -end note - -FA_SERVER(cactusserverside,"Hyperledger Cactus Server Side") - -FA_DATABASE(dlt,"Distributed Ledger") - -actor1 ..|> mobiledevice: Decides to execute transaction -mobiledevice ..|> cactusserverside: Send already signed transaction data -cactusserverside ..|> dlt: Forward signed transaction as-is - -@enduml diff --git a/whitepaper/communication-protocol-between-blp-and-lp.png b/whitepaper/communication-protocol-between-blp-and-lp.png deleted file mode 100644 index 1d8788da12..0000000000 Binary files a/whitepaper/communication-protocol-between-blp-and-lp.png and /dev/null differ diff --git a/whitepaper/communication-protocol-between-blp-and-lp.puml b/whitepaper/communication-protocol-between-blp-and-lp.puml deleted file mode 100644 index e1245825be..0000000000 --- a/whitepaper/communication-protocol-between-blp-and-lp.puml +++ /dev/null @@ -1,167 +0,0 @@ -@startuml -title The communication protocol between Business Logic Plugin and Ledger Plugin - -actor "End User" as euser -actor "Administrator" as admin - -box "Routing Interface" #LightGray -entity "Routing Interface" as rif -end box - -database "BLP registory" as blp_registry - -box "Business Logic Plugin" #Aquamarine -entity "Business Logic Plugin" as blp -end box -box "Ledger Plugin" #Lavender -entity "Verifier" as verifier -entity "Validator" as validator -end box -database "ledger" as ledger - -== Initialize connecting with a ledger == -admin -> rif: startService()\nrequest -activate rif -rif -> blp_registry: getLedgerPluginInfoList() -activate blp_registry -blp_registry --> rif: list of LedgerPluignInfo -deactivate -rif -> verifier: connect()\n (with ValidatorInfo) -activate verifier -verifier -> validator: open socket.io\n connection -activate validator -validator -> validator: authenticate Verifier -validator -> ledger: setup parameters \nto call a ledger node -activate ledger -ledger --> validator: calling successed -deactivate ledger -validator --> verifier: connection\n established -deactivate validator -verifier --> rif: connect() OK -deactivate verifier -rif -> blp_registry: update LedgerPluginInfo\n as activated -activate blp_registry -blp_registry --> rif: update OK -deactivate blp_registry -rif -> verifier: startMonitor() -activate verifier -verifier -> validator: startMonitor()\nover socket.io -activate validator -validator -> validator: start monitoring -validator --> verifier: startMonitor() OK -deactivate validator -verifier --> rif: startMonitor() OK -deactivate verifier -rif --> admin: startService() OK -deactivate rif -... - -== Send a ledger operation request == - -euser -> rif: POST /api/v1/bl/trades/\n(request of creating a trade) -activate rif -rif -> rif: assign tradeID -rif -> blp: startBL(businessLogicID) -activate blp -blp -> blp: event triggered\n (startBL) -blp -> blp: load scenario\n to determine next operation -blp -> blp: load message template\n of transaction request -blp -> blp: make a signedTransaction -blp -> rif: sendSignedTransaction(signedTransaction) -activate rif -rif -> rif: register TxID\n with associated tradeID -rif -> verifier: sendSignedTransaction(signedTransaction) -activate verifier -verifier -> validator: sendSignedTransaction(signedTransaction)\nover socket.io -activate validator -validator -> ledger: submit transaction -activate ledger -ledger --> validator: submit transaction OK -deactivate ledger -deactivate validator -verifier --> rif: sendSignedTransaction()\nrequest OK -deactivate verifier -rif --> blp: sendSignedTransaction()\n request OK -deactivate rif -blp -> blp: event triggered\n (state of trade changed) -blp --> rif: startBL() OK -deactivate blp -rif --> euser: POST /api/v1/bl/trades/ OK\n with tradeID -deactivate rif -deactivate validator -... - -== Send a event notification == - -ledger -> ledger: new block data\n is generated -activate ledger -ledger -> validator: notify block data -activate validator -validator --> ledger: return OK -deactivate ledger -validator -> validator: disasmble into transactions \nand validate each -validator -> validator: create LedgerEvent message \nfrom disambled transactions -validator -> validator: add signature\n on LedgerEvent message -validator -> verifier: send a signed \nLedgerEvent\n message -deactivate validator -activate verifier -verifier -> verifier: verify signature\n on an LedgerEvent\n message -verifier -> rif: notify LedgerEvent message -activate rif -rif --> verifier: notify LedgerEvent\n message OK -deactivate verifier -rif -> rif: parse LedgerEvent message \nto determine which tradeID \nand business logic is associated -rif -> blp: notify LedgerEvent \nto associated business logic -activate blp -blp -> blp: event triggered\n (state of the trade changed) -blp -> blp: load scenario\n to determine next operation - -blp -> blp: (If there is a next operation,\nthe following processing continues \nas the same as the sequence of\n"Send a ledger operation request") -blp -> blp: load message template\n of transaction request -blp -> blp: make a signedTransaction -blp -> rif: sendSignedTransaction(signedTransaction) -activate rif -rif -> rif: register TxID\n with associated tradeID -rif -> verifier: sendSignedTransaction(signedTransaction) -activate verifier -verifier -> validator: sendSignedTransaction(signedTransaction)\n over socket.io -activate validator -validator -> ledger: submit transaction -activate ledger -ledger --> validator: submit transaction OK -deactivate ledger -deactivate validator -verifier --> rif: sendSignedTransaction()\nrequest OK -deactivate verifier -rif --> blp: sendSignedTransaction()\nrequest OK -deactivate rif -blp -> blp: event triggered (state of trade changed) -blp --> rif: notify LedgerEvent OK -deactivate blp -deactivate verifier -rif -> rif: update 'last observed block#' -deactivate rif -... - -== shutdown a connection == -admin -> rif: stopServer() request -activate rif -rif -> rif: shutdown operation is invoked -rif -> rif: enumerate active ledgers -rif -> verifier: stopMonitor() -activate verifier -verifier -> validator: send a message\n over socket.io -activate validator -validator -> validator: stopMonitor() -verifier --> rif: stopMonitor() OK -deactivate validator -deactivate verifier -rif -> verifier: disconnect() -activate verifier -verifier -> verifier: close socket.io\n connection -verifier --> rif: disconnect() OK -deactivate verifier -rif --> admin: stopServer() OK -deactivate rif - -@enduml \ No newline at end of file diff --git a/whitepaper/deeplists.tex b/whitepaper/deeplists.tex deleted file mode 100644 index 3776db45b8..0000000000 --- a/whitepaper/deeplists.tex +++ /dev/null @@ -1,24 +0,0 @@ -\usepackage{enumitem} -\setlistdepth{9} - -\setlist[itemize,1]{label=$\bullet$} -\setlist[itemize,2]{label=$\bullet$} -\setlist[itemize,3]{label=$\bullet$} -\setlist[itemize,4]{label=$\bullet$} -\setlist[itemize,5]{label=$\bullet$} -\setlist[itemize,6]{label=$\bullet$} -\setlist[itemize,7]{label=$\bullet$} -\setlist[itemize,8]{label=$\bullet$} -\setlist[itemize,9]{label=$\bullet$} -\renewlist{itemize}{itemize}{9} - -\setlist[enumerate,1]{label=$\arabic*.$} -\setlist[enumerate,2]{label=$\alph*.$} -\setlist[enumerate,3]{label=$\roman*.$} -\setlist[enumerate,4]{label=$\arabic*.$} -\setlist[enumerate,5]{label=$\alpha*$} -\setlist[enumerate,6]{label=$\roman*.$} -\setlist[enumerate,7]{label=$\arabic*.$} -\setlist[enumerate,8]{label=$\alph*.$} -\setlist[enumerate,9]{label=$\roman*.$} -\renewlist{enumerate}{enumerate}{9} diff --git a/whitepaper/deployIntegrationFramework.png b/whitepaper/deployIntegrationFramework.png deleted file mode 100644 index b79af9f71b..0000000000 Binary files a/whitepaper/deployIntegrationFramework.png and /dev/null differ diff --git a/whitepaper/deployment-entity-relationship-diagram.png b/whitepaper/deployment-entity-relationship-diagram.png deleted file mode 100644 index c6f6cbca9a..0000000000 Binary files a/whitepaper/deployment-entity-relationship-diagram.png and /dev/null differ diff --git a/whitepaper/deployment-entity-relationship-diagram.puml b/whitepaper/deployment-entity-relationship-diagram.puml deleted file mode 100644 index a1615e995e..0000000000 --- a/whitepaper/deployment-entity-relationship-diagram.puml +++ /dev/null @@ -1,78 +0,0 @@ -@startuml deployment-entity-relationship-diagram - -!include -' To import the sprite file you DON'T need to place a prefix! -!include -!include -!include - -title Deployment Entity Relationship Diagram\n\nHyperledger Cactus - - -namespace Physical_Deplyoment_Elements { - - entity CactusNode <> { - * id: string - -- - * nodeApiHost: string - * consortiumId: string - * memberId: string - * publicKeyPem: string - * plugins: Array - * ledgers: Array - } - - entity APIServer <> { - * plugins: Array - } - - interface "ICactusPlugin" <> { - * getInstanceId(): string - -- - * getPackageName(): string - } - - entity "PluginInstance" <> implements ICactusPlugin { - + instanceId: string - + packageName: string - } -} - -entity "CactusConsortium" <> { - * id: string - -- - * mainApiHost: string - * members: Array -} - -entity "ConsortiumMember" <> { - * id: string - -- - * nodes: Array -} - -enum LedgerType <> { - - BESU_1X - - BESU_2X - - BURROW_0X - - CORDA_4X - - FABRIC_14X - - FABRIC_2 - - QUORUM_2X - - SAWTOOTH_1X - - ... -} - -entity Ledger <> { - * id: string - -- - * ledgerType: LedgerType -} - -CactusNode }|-- ConsortiumMember -ConsortiumMember }|-- CactusConsortium -APIServer }|-- CactusNode -PluginInstance }|-- APIServer -Ledger .. LedgerType - -@enduml diff --git a/whitepaper/deployment-low-resource-example.png b/whitepaper/deployment-low-resource-example.png deleted file mode 100644 index b5071b632c..0000000000 Binary files a/whitepaper/deployment-low-resource-example.png and /dev/null differ diff --git a/whitepaper/deployment-low-resource-example.puml b/whitepaper/deployment-low-resource-example.puml deleted file mode 100644 index 025e7e145c..0000000000 --- a/whitepaper/deployment-low-resource-example.puml +++ /dev/null @@ -1,91 +0,0 @@ -@startuml deployment-low-resource-example - -!include -' To import the sprite file you DON'T need to place a prefix! -!include -!include -!include - -left to right direction - -title Deployment\nLow Resource Example\nHyperledger Cactus - -rectangle Developer_Machine as developermachine #EEEEEE { - - rectangle Consortium as consortium #BBBBBB { - - rectangle Member_A as membera #00CC00 { - rectangle Node_A as nodea #CCCC00 { - rectangle API_Server_A_1 as apiservera1 #00BBBB { - component "TCP:8080" #FF00FF { - } - rectangle Plugin_Ledger_Connector_A_1 as ledgerconnectora1 { - } - rectangle Plugin_Keychain_A_1 as keychaina1 { - } - rectangle Plugin_Consortium_Management_A_1 as consortiummanagementa1 { - } - } - rectangle API_Server_A_2 as apiservera2 #00BBBB { - component "TCP:7080" #FF00FF { - } - rectangle Plugin_Ledger_Connector_A_2 as ledgerconnectora2 { - } - rectangle Plugin_Keychain_A_2 as keychaina2 { - } - rectangle Plugin_Consortium_Management_A_2 as consortiummanagementa2 { - } - } - rectangle API_Server_A_3 as apiservera3 #00BBBB { - component "TCP:6080" #FF00FF { - } - rectangle Plugin_Ledger_Connector_A_3 as ledgerconnectora3 { - } - rectangle Plugin_Keychain_A_3 as keychaina3 { - } - rectangle Plugin_Consortium_Management_A_3 as consortiummanagementa3 { - } - } - } - } - - rectangle Member_B as memberb #00CC00 { - rectangle Node_B as nodeb #CCCC00 { - rectangle API_Server_B_1 as apiserverb1 #00BBBB { - component "TCP:18080" #FF00FF { - } - rectangle Plugin_Ledger_Connector_B_1 as ledgerconnectorb1 { - } - rectangle Plugin_Keychain_B_1 as keychainb1 { - } - rectangle Plugin_Consortium_Management_B_1 as consortiummanagementb1 { - } - } - rectangle API_Server_B_2 as apiserverb2 #00BBBB { - component "TCP:17080" #FF00FF { - } - rectangle Plugin_Ledger_Connector_B_2 as ledgerconnectorb2 { - } - rectangle Plugin_Keychain_B_2 as keychainb2 { - } - rectangle Plugin_Consortium_Management_B_2 as consortiummanagementb2 { - } - } - rectangle API_Server_B_3 as apiserverb3 #00BBBB { - component "TCP:16080" #FF00FF { - } - rectangle Plugin_Ledger_Connector_B_3 as ledgerconnectorb3 { - } - rectangle Plugin_Keychain_B_3 as keychainb3 { - } - rectangle Plugin_Consortium_Management_B_3 as consortiummanagementb3 { - } - } - } - } - } -} - -membera -[hidden]- memberb - -@enduml diff --git a/whitepaper/deployment-production-example.png b/whitepaper/deployment-production-example.png deleted file mode 100644 index 8628041c46..0000000000 Binary files a/whitepaper/deployment-production-example.png and /dev/null differ diff --git a/whitepaper/deployment-production-example.puml b/whitepaper/deployment-production-example.puml deleted file mode 100644 index feb1c3d1c2..0000000000 --- a/whitepaper/deployment-production-example.puml +++ /dev/null @@ -1,88 +0,0 @@ -@startuml deployment-production-example - -!include -' To import the sprite file you DON'T need to place a prefix! -!include -!include -!include - -left to right direction - -title Deployment\nProduction Example\nHyperledger Cactus - -rectangle Consortium as consortium #EEEEEE { - - rectangle Member_A as membera #00CC00 { - rectangle Data_Center_A #BBBBBB { - rectangle Load_Balancer_A as loadbalancera #00FFFF { - component "https://node-a.consortium.example.com" { - } - } - rectangle Node_A as nodea #CCCC00 { - rectangle API_Server_A_1 as apiservera1 #00BBBB { - rectangle Plugin_Ledger_Connector_A_1 as ledgerconnectora1 { - } - rectangle Plugin_Keychain_A_1 as keychaina1 { - } - rectangle Plugin_Consortium_Management_A_1 as consortiummanagementa1 { - } - } - rectangle API_Server_A_2 as apiservera2 #00BBBB { - rectangle Plugin_Ledger_Connector_A_2 as ledgerconnectora2 { - } - rectangle Plugin_Keychain_A_2 as keychaina2 { - } - rectangle Plugin_Consortium_Management_A_2 as consortiummanagementa2 { - } - } - rectangle API_Server_A_3 as apiservera3 #00BBBB { - rectangle Plugin_Ledger_Connector_A_3 as ledgerconnectora3 { - } - rectangle Plugin_Keychain_A_3 as keychaina3 { - } - rectangle Plugin_Consortium_Management_A_3 as consortiummanagementa3 { - } - } - } - } - } - - rectangle Member_B as memberb #00CC00 { - rectangle Data_Center_B #BBBBBB { - rectangle Load_Balancer_B as loadbalancerb #00FFFF { - component "https://node-b.consortium.example.com" { - } - } - rectangle Node_B as nodeb #CCCC00 { - rectangle API_Server_B_1 as apiserverb1 #00BBBB { - rectangle Plugin_Ledger_Connector_B_1 as ledgerconnectorb1 { - } - rectangle Plugin_Keychain_B_1 as keychainb1 { - } - rectangle Plugin_Consortium_Management_B_1 as consortiummanagementb1 { - } - } - rectangle API_Server_B_2 as apiserverb2 #00BBBB { - rectangle Plugin_Ledger_Connector_B_2 as ledgerconnectorb2 { - } - rectangle Plugin_Keychain_B_2 as keychainb2 { - } - rectangle Plugin_Consortium_Management_B_2 as consortiummanagementb2 { - } - } - rectangle API_Server_B_3 as apiserverb3 #00BBBB { - rectangle Plugin_Ledger_Connector_B_3 as ledgerconnectorb3 { - } - rectangle Plugin_Keychain_B_3 as keychainb3 { - } - rectangle Plugin_Consortium_Management_B_3 as consortiummanagementb3 { - } - } - } - } - } -} - -membera -[hidden]- memberb - -@enduml diff --git a/whitepaper/documentStorageDeploymentDiag.png b/whitepaper/documentStorageDeploymentDiag.png deleted file mode 100644 index 64daaadec7..0000000000 Binary files a/whitepaper/documentStorageDeploymentDiag.png and /dev/null differ diff --git a/whitepaper/escrowedSaleDataforCoins.png b/whitepaper/escrowedSaleDataforCoins.png deleted file mode 100644 index 448d4d5309..0000000000 Binary files a/whitepaper/escrowedSaleDataforCoins.png and /dev/null differ diff --git a/whitepaper/exampleCoinPeggedtoBitcoin.png b/whitepaper/exampleCoinPeggedtoBitcoin.png deleted file mode 100644 index 0d98dc987f..0000000000 Binary files a/whitepaper/exampleCoinPeggedtoBitcoin.png and /dev/null differ diff --git a/whitepaper/feature-value-transfer.png b/whitepaper/feature-value-transfer.png deleted file mode 100644 index 6733e8040b..0000000000 Binary files a/whitepaper/feature-value-transfer.png and /dev/null differ diff --git a/whitepaper/feature-value-transfer.puml b/whitepaper/feature-value-transfer.puml deleted file mode 100644 index 916e13f47d..0000000000 --- a/whitepaper/feature-value-transfer.puml +++ /dev/null @@ -1,120 +0,0 @@ -@startuml -title Value Transfer - -participant "User A" as user -box "Hyperledger Cactus" #lightGrey -entity "Service App" as sapp -entity "API Server" as apis -entity "Validator1" as validator_1 -entity "Validator2" as validator_2 -end box - -box "Ledgers" #orange -database "Ledger1" as ledger_1 -database "Ledger2" as ledger_2 -end box - -user -> sapp: "Request asset transfer \nfrom Ledger1 to Ledger2" -activate sapp - -== Lock Ledger1 asset until Ledger2 asset transfer is completed == -sapp -> apis: "Request to lock \nLedger1 asset" -activate apis - -apis ->> ledger_1: "Invoke smart contract\n to transfer asset" -sapp <<-- apis: "Request posted" -deactivate apis -user <<-- sapp: "Request accepted" -deactivate sapp - -activate ledger_1 -ledger_1 -> ledger_1: "Consensus completed" -validator_1 <<- ledger_1: "Notify new block data" -deactivate ledger_1 -activate validator_1 - -validator_1 -> validator_1: "Validate transactions" -validator_1 -> validator_1: "digital sign on \nvalid transaction" - -validator_1 -> apis: "Request to update\n transaction status" -activate apis -apis -> apis: "Update transaction \nstatus(asset locked)" -apis -->> validator_1: "transaction update\n accepted" -deactivate validator_1 - -sapp <- apis: "Notify transaction \nstatus update" -activate sapp -sapp -> sapp: "update state" -sapp -->> apis: "notification received" -deactivate apis - -sapp -> sapp: "determine \nnext operation\n(transfer Ledger2 asset)" - -== Transfer Ledger2 Asset == - -sapp -> apis: "Request to \ntransfer Ledger2 asset" -activate apis -apis ->> ledger_2: "Invoke smart contract\n to transfer asset" -sapp <<-- apis: "Request posted" -deactivate apis -deactivate sapp - -activate ledger_2 -ledger_2 -> ledger_2: "Consensus completed" -validator_2 <<- ledger_2: "Notify new block data" -deactivate ledger_2 -activate validator_2 - -validator_2 -> validator_2: "Validate transactions" -validator_2 -> validator_2: "digital sign on \nvalid transaction" - -validator_2 -> apis: "Request to update\n transaction status" -activate apis -apis -> apis: "Update transaction \nstatus" -apis -->> validator_2: "transaction update\n accepted" -deactivate validator_2 - -sapp <- apis: "Notify transaction \nstatus update" -activate sapp -sapp -> sapp: "update state" -sapp -->> apis: "notification received" -deactivate apis - -sapp -> sapp: "determine \nnext operation\n(Settle transfered \nLedger1 asset)" - -== Settle transfered Ledger1 asset == -sapp -> apis: "Request to transfer (unlock?) \nLedger1 asset" -activate apis - -apis ->> ledger_1: "Invoke smart contract\n to transfer asset" -sapp <<-- apis: "Request posted" -deactivate apis -user <<-- sapp: "Request accepted" -deactivate sapp - -activate ledger_1 -ledger_1 -> ledger_1: "Consensus completed" -validator_1 <<- ledger_1: "Notify new block data" -deactivate ledger_1 -activate validator_1 - -validator_1 -> validator_1: "Validate transactions" -validator_1 -> validator_1: "digital sign on \nvalid transaction" - -validator_1 -> apis: "Request to update\n transaction status" -activate apis -apis -> apis: "Update transaction \nstatus(asset locked)" -apis -->> validator_1: "transaction update\n accepted" -deactivate validator_1 - -sapp <- apis: "Notify transaction \nstatus update" -activate sapp -sapp -> sapp: "update state" -sapp -->> apis: "notification received" -deactivate apis - -sapp -> sapp: "determine \nnext operation\n(no more operation)" -deactivate sapp - - -@enduml diff --git a/whitepaper/foodTraceIntegration2.png b/whitepaper/foodTraceIntegration2.png deleted file mode 100644 index df2f011c84..0000000000 Binary files a/whitepaper/foodTraceIntegration2.png and /dev/null differ diff --git a/whitepaper/foodTraceIntergration.png b/whitepaper/foodTraceIntergration.png deleted file mode 100644 index 4c8ef4188c..0000000000 Binary files a/whitepaper/foodTraceIntergration.png and /dev/null differ diff --git a/whitepaper/healthcareDataSharingwithAccessControlList.png b/whitepaper/healthcareDataSharingwithAccessControlList.png deleted file mode 100644 index cf16c198df..0000000000 Binary files a/whitepaper/healthcareDataSharingwithAccessControlList.png and /dev/null differ diff --git a/whitepaper/hyperledgerBCIntegrationFramework.png b/whitepaper/hyperledgerBCIntegrationFramework.png deleted file mode 100644 index a21ec3a85c..0000000000 Binary files a/whitepaper/hyperledgerBCIntegrationFramework.png and /dev/null differ diff --git a/whitepaper/integration-framework-client-side-transaction-signing.png b/whitepaper/integration-framework-client-side-transaction-signing.png deleted file mode 100644 index 66dee0ac67..0000000000 Binary files a/whitepaper/integration-framework-client-side-transaction-signing.png and /dev/null differ diff --git a/whitepaper/integration-framework-plugin-architecture.png b/whitepaper/integration-framework-plugin-architecture.png deleted file mode 100644 index 9f41d9dba4..0000000000 Binary files a/whitepaper/integration-framework-plugin-architecture.png and /dev/null differ diff --git a/whitepaper/integration-framework-server-side-transaction-signing.png b/whitepaper/integration-framework-server-side-transaction-signing.png deleted file mode 100644 index 082f6d1108..0000000000 Binary files a/whitepaper/integration-framework-server-side-transaction-signing.png and /dev/null differ diff --git a/whitepaper/integration-framework-unified-identity-management.png b/whitepaper/integration-framework-unified-identity-management.png deleted file mode 100644 index d74beddcc9..0000000000 Binary files a/whitepaper/integration-framework-unified-identity-management.png and /dev/null differ diff --git a/whitepaper/interworking-architecture-diagram.png b/whitepaper/interworking-architecture-diagram.png deleted file mode 100644 index 6e3c242b8b..0000000000 Binary files a/whitepaper/interworking-architecture-diagram.png and /dev/null differ diff --git a/whitepaper/interworking-architecture-diagram.puml b/whitepaper/interworking-architecture-diagram.puml deleted file mode 100644 index 591a1c8afd..0000000000 --- a/whitepaper/interworking-architecture-diagram.puml +++ /dev/null @@ -1,55 +0,0 @@ -@startuml interworking-architecture-diagram - -!include -' To import the sprite file you DON'T need to place a prefix! - -title Interworking architecture diagram - -node "Hyperledger Cactus Web application or Smart contract on a blockchain" as web_app { - rectangle "TX submitter / TX verifier" as txverifier1 { - } - rectangle "TX submitter / TX verifier" as txverifier2 { - } -} - -node "API server-1" as api_server1 { - rectangle "API server-plugin1" as api_server_plugin1 { - } -} - -node "API server-2" as api_server2 { - rectangle "API server-plugin2" as api_server_plugin2 { - } -} - -rectangle "Ledger-1" as ledger1 { - node "Node" as ledger1_node1 { - } - node "Node" as ledger1_node2 { - } - node "Node" as ledger1_node3 { - } - node "Node" as ledger1_node4 { - } -} - -rectangle "Ledger-2" as ledger2 { - node "Node" as ledger2_node1 { - } - node "Node" as ledger2_node2 { - } - node "Node" as ledger2_node3 { - } - node "Node" as ledger2_node4 { - } -} - -actor "Application User" as app_user - -txverifier1 <===> api_server_plugin1: secure bi-directional channel -txverifier2 <===> api_server_plugin2: secure bi-directional channel -api_server_plugin1 <===> ledger1 -api_server_plugin2 <===> ledger2 -app_user ..> web_app: API call - -@enduml diff --git a/whitepaper/ledger_entry_point_coordination.png b/whitepaper/ledger_entry_point_coordination.png deleted file mode 100644 index b678b1187c..0000000000 Binary files a/whitepaper/ledger_entry_point_coordination.png and /dev/null differ diff --git a/whitepaper/ledger_entry_point_coordination.pptx b/whitepaper/ledger_entry_point_coordination.pptx deleted file mode 100644 index 6b66ef27f1..0000000000 Binary files a/whitepaper/ledger_entry_point_coordination.pptx and /dev/null differ diff --git a/whitepaper/ledger_interaction.png b/whitepaper/ledger_interaction.png deleted file mode 100644 index 8452f38e04..0000000000 Binary files a/whitepaper/ledger_interaction.png and /dev/null differ diff --git a/whitepaper/ledger_interaction.pptx b/whitepaper/ledger_interaction.pptx deleted file mode 100644 index 2e38a3db1e..0000000000 Binary files a/whitepaper/ledger_interaction.pptx and /dev/null differ diff --git a/whitepaper/ledger_transfer_one_way.png b/whitepaper/ledger_transfer_one_way.png deleted file mode 100644 index 7d2785d936..0000000000 Binary files a/whitepaper/ledger_transfer_one_way.png and /dev/null differ diff --git a/whitepaper/ledger_transfer_one_way.pptx b/whitepaper/ledger_transfer_one_way.pptx deleted file mode 100644 index 4bae1c4c92..0000000000 Binary files a/whitepaper/ledger_transfer_one_way.pptx and /dev/null differ diff --git a/whitepaper/ledger_transfer_two_way.png b/whitepaper/ledger_transfer_two_way.png deleted file mode 100644 index 7f40662b63..0000000000 Binary files a/whitepaper/ledger_transfer_two_way.png and /dev/null differ diff --git a/whitepaper/ledger_transfer_two_way.pptx b/whitepaper/ledger_transfer_two_way.pptx deleted file mode 100644 index 27866ea7f6..0000000000 Binary files a/whitepaper/ledger_transfer_two_way.pptx and /dev/null differ diff --git a/whitepaper/pandoc.css b/whitepaper/pandoc.css deleted file mode 100644 index cfc5f70d0d..0000000000 --- a/whitepaper/pandoc.css +++ /dev/null @@ -1,8 +0,0 @@ - \ No newline at end of file diff --git a/whitepaper/plugin-architecture-component-diagram.puml b/whitepaper/plugin-architecture-component-diagram.puml deleted file mode 100644 index fdfcd1a25f..0000000000 --- a/whitepaper/plugin-architecture-component-diagram.puml +++ /dev/null @@ -1,47 +0,0 @@ - -@startuml Plugin Architecture - -!include -!include -!include -!include -!include - -title Hyperledger Cactus\nPlugin Architecture - -' left to right direction -' allow_mixing -skinparam DefaultTextAlignment center -skinparam Linetype ortho -skinparam sequenceArrowThickness 2 -skinparam roundcorner 5 -skinparam maxmessagesize 30 -skinparam sequenceParticipant underline - -' actor "Application User" as actor1 <> -' FA_MOBILE(mobiledevice,"Mobile Device") - -box "End Users" #LightBlue - actor Bob -end box - -box "Hyperledger Cactus Deployment" #LightGrey - collections "API Server Node(s)" as ApiServer - participant FabricConnectorPlugin -end box - -box "Ledger Deployments" #LightSalmon - database "Fabric Network" as FabricNetwork -end box - -Bob -> ApiServer : Request Transaction Execution -activate ApiServer -ApiServer -> FabricConnectorPlugin: Call Transaction Execution Plugin -activate FabricConnectorPlugin -FabricConnectorPlugin -> FabricNetwork: Request Transaction Execution -activate FabricNetwork -return Transaction Results -return Transaction Results -return Transaction Results - -@enduml diff --git a/whitepaper/plugin-consortium-manual-bootstrap-sequence-diagram.png b/whitepaper/plugin-consortium-manual-bootstrap-sequence-diagram.png deleted file mode 100644 index a96bb3b3a3..0000000000 Binary files a/whitepaper/plugin-consortium-manual-bootstrap-sequence-diagram.png and /dev/null differ diff --git a/whitepaper/plugin-consortium-manual-bootstrap-sequence-diagram.puml b/whitepaper/plugin-consortium-manual-bootstrap-sequence-diagram.puml deleted file mode 100644 index 8d09311ec2..0000000000 --- a/whitepaper/plugin-consortium-manual-bootstrap-sequence-diagram.puml +++ /dev/null @@ -1,58 +0,0 @@ -@startuml Sequence Diagram - Plugin Consortium Manual Bootstrap - -skinparam ArrowFontStyle italic - -title Hyperledger Cactus\nSequence Diagram - Plugin Consortium Manual Bootstrap - -box Humans -actor Business_Organization_A as a <> -actor Business_Organization_B as b <> -end box - -box Cactus Node A -entity "API Server A" as apia <> -end box - -box Cactus Node B -entity "API Server B" as apib <> -end box - -autoactivate off -autonumber - -== Manual Consensus == - -a -> b: Propose forming consortium\n(email, met in cafe, etc.) -return Consent to consortium formation - -a -> b: Propose trusted communication\nchannel (corporate email or\ntrusted courier service/etc.) -return Consent to proposed\ncommunication channel -note over a,b -This is where **trust** is established between the consortium members. -If the selected channel is compromised in any way, that's an active MITM! -end note - -== Provision Resources, Bootstrap Consortium == - -a->a: Generate key(s) of node(s) -a->a: Provision hardware resources\n(server,public IP, DNS) -a->a: Decide on plugins to be used - -b->b: Generate key(s) of node(s) -b->b: Provision hardware resources\n(server,public IP, DNS) -b->b: Decide on plugins to be used - -a -> b: A sends node hosts,public keys to B -return B responds in kind with their own -note over a,b -As mentioned above, if the communication was compromised, MITM can be -executed at this point by the attacker by altering the keys/hosts in transit. -end note - -a->apia: Configure consortium\nplugin with keys,hosts -a->apia: Start Cactus API Server - -b->apib: Configure consortium\nplugin with keys,hosts -b->apib: Start Cactus API Server - -@enduml diff --git a/whitepaper/related-work-categories.png b/whitepaper/related-work-categories.png deleted file mode 100644 index c773260f13..0000000000 Binary files a/whitepaper/related-work-categories.png and /dev/null differ diff --git a/whitepaper/server-side-transaction-signing-deployment-diagram.puml b/whitepaper/server-side-transaction-signing-deployment-diagram.puml deleted file mode 100644 index 76036723e1..0000000000 --- a/whitepaper/server-side-transaction-signing-deployment-diagram.puml +++ /dev/null @@ -1,36 +0,0 @@ - -@startuml Server Side Transaction Signing - -!include -!include -!include -!include -!include - -title Hyperledger Cactus\nServer Side Transaction Signing - -left to right direction -' allow_mixing -skinparam DefaultTextAlignment center -skinparam Linetype ortho -skinparam sequenceArrowThickness 2 -skinparam roundcorner 5 -skinparam maxmessagesize 30 -skinparam sequenceParticipant underline - -actor "Application User" as actor1 <> - -FA_MOBILE(mobiledevice,"Mobile Device") - -FA_SERVER(cactusserverside,"Hyperledger Cactus Server Side\n<&key>") -note bottom of cactusserverside #LightSkyBlue - <&key> Private key of user resides on Hyperledger Cactus server side -end note - -FA_DATABASE(dlt,"Distributed Ledger") - -actor1 ..|> mobiledevice: Decides to execute transaction -mobiledevice ..|> cactusserverside: Send unsigned transaction data -cactusserverside ..|> dlt: Send signed transaction data - -@enduml diff --git a/whitepaper/unified-identity-management.puml b/whitepaper/unified-identity-management.puml deleted file mode 100644 index 257f9a8c96..0000000000 --- a/whitepaper/unified-identity-management.puml +++ /dev/null @@ -1,58 +0,0 @@ -@startuml Unified Identity Management -title Hyperledger Cactus\nUnified Identity Management - -' left to right direction - -' skinparam Linetype ortho -skinparam sequenceArrowThickness 2 -skinparam roundcorner 5 -skinparam maxmessagesize 30 -skinparam sequenceParticipant underline - -allow_mixing - -package "Hyperledger Cactus Identity" as cactusidentity #LightGray { - object "DLT Identity 1" as dlti1 <> - object "DLT Identity 2" as dlti2 <> - object "DLT Identity N" as dltin <> -} - -actor "Application User" as actor1 <> - -frame "Hyperledger Cactus" <> #LightCyan { - - package "pkg-cmd-api-server" as pkgcmdapiserver #LightGreen { - component "/api/v1/identity/authenticate\n<>" as authenticateendpoint - component "/api/v1/identity/add-credential\n<>" as addcredentialendpoint - } - - package "pkg-identity" as pkgidentity #LightGreen { - component "IdentityService\n<>" as identityservice - } - - package "pkg-sql-storage" as pkgsqlstorage #LightGreen { - component "SqlStorageService\n<>" as sqlstorageservice - } - - package "pkg-keychain" as pkgkeychain #LightGreen { - component "KeychainService\n<>" as keychainservice - } -} - -actor1 .down. dlti1 -actor1 .down. dlti2 -actor1 .down. dltin - -actor1 .right.> addcredentialendpoint -note on link: Associate DLT\nIdentity to Hyperledger Cactus\nidentity - -addcredentialendpoint ..> pkgidentity -note on link: Store identity credentials - -pkgidentity ..> pkgkeychain -note on link: Store identity credentials - -addcredentialendpoint ..> pkgsqlstorage -note on link: Store Hyperledger Cactus/DLT identity relationships - -@enduml diff --git a/whitepaper/use-case-authentication-authorization-permissioned-chains.puml b/whitepaper/use-case-authentication-authorization-permissioned-chains.puml deleted file mode 100644 index abdadbc182..0000000000 --- a/whitepaper/use-case-authentication-authorization-permissioned-chains.puml +++ /dev/null @@ -1,74 +0,0 @@ -@startuml Authentication, Authorization for Permissioned Chains - -title Hyperledger Cactus\nAuthentication, Authorization for Permissioned Chains - -left to right direction - -skinparam sequenceArrowThickness 2 -skinparam roundcorner 5 -skinparam maxmessagesize 30 -skinparam sequenceParticipant underline - -frame "End User Application" as eu { - actor "<>" as io - node "Identity Proof 1\n<>" as ppkp1 #PaleVioletRed { - } - node "Identity Proof 2\n<>" as ppkp2 #PaleVioletRed { - } - node "Identity Proof 3\n<>" as password #PaleVioletRed { - } - node "Identity Proof 4\n<>" as authtoken #PaleVioletRed { - } -} - - -frame "Company A\n<>" as ca #LightGray { - node "Hyperledger Cactus\n<>" as Hyperledger Cactus #LightYellow { - node "REST API\n<>" as cactusrestapi #LightGreen { - } - together { - node "Network A\n<>" as cactusidpluginnetworka #LightGreen { - } - node "Network B\n<>" as cactusidpluginnetworkb #LightGreen { - } - node "Network A\n<>" as cactusconnectorpluginnetworka #LightGreen { - } - node "Network B\n<>" as cactusconnectorpluginnetworkb #LightGreen { - } - } - } -} - -frame "Network A\n<>" as na #LightGray { - node "Wallet 1 of End User\n<
>" as weua #LightYellow { - } -} - -frame "Network B\n<>" as nb #LightGray { - node "Wallet 2 of End User\n<
>" as weub #LightYellow { - } -} - -io ..> cactusrestapi: Request transactions -note on link - Uses one or more of the - identity proofs for each - request that Hyperledger Cactus - verifies/passes along - via the appropriate plugins - before instructing the - participating ledgers - to execute transactions: - 1. Export data - 2. Transfer coins - 3. Manage permissions - 4. etc. -end note -cactusrestapi <..> cactusconnectorpluginnetworka -cactusrestapi <..> cactusconnectorpluginnetworkb -cactusrestapi <..> cactusidpluginnetworka -cactusrestapi <..> cactusidpluginnetworkb -cactusconnectorpluginnetworka ..> na: Execute transactions -cactusconnectorpluginnetworkb ..> nb: Execute transactions - -@enduml diff --git a/whitepaper/use-case-ethereum-to-quorum-asset-transfer.png b/whitepaper/use-case-ethereum-to-quorum-asset-transfer.png deleted file mode 100644 index 2887b5901a..0000000000 Binary files a/whitepaper/use-case-ethereum-to-quorum-asset-transfer.png and /dev/null differ diff --git a/whitepaper/use-case-ethereum-to-quorum-asset-transfer.puml b/whitepaper/use-case-ethereum-to-quorum-asset-transfer.puml deleted file mode 100644 index c67b145596..0000000000 --- a/whitepaper/use-case-ethereum-to-quorum-asset-transfer.puml +++ /dev/null @@ -1,169 +0,0 @@ -@startuml -title Ethereum to Quorum Asset Transfer - -participant "Application user" as user - -box "Routing Interface" #LightGray -entity "Routing Interface" as routing_if -end box -box "Business Logic Plugin" #Aquamarine -entity "Business Logic Plugin" as business_lp -end box -box "Ledger Plugin (for Ledger1)" #Lavender -entity "Verifier 1" as verifier_1 -entity "Validator 1" as validator_1 -end box -box "Ledger Plugin (for Ledger 2)" #Lavender -entity "Verifier 2" as verifier_2 -entity "Validator 2" as validator_2 -end box - -box "Ledgers" #LightCyan -database "Ethereum Ledger" as ledger_1 -database "Quorum Ledger" as ledger_2 -end box - -user -> routing_if: "Request asset transfer \nfrom Ethereum to Quorum" -activate routing_if -routing_if -> business_lp: "Request asset transfer \nfrom Ethereum to Quorum" -activate business_lp - -== Escrow Ethereum asset until Quorum asset transfer is completed == - -/'** From: Business_lp, To: Ledger_1, Act: Escrow transaction **'/ -business_lp -> routing_if: "Request to invoke smart contract\n to transfer asset" -routing_if -> verifier_1: "Request to invoke smart contract\n to transfer asset" -activate verifier_1 -verifier_1 -> validator_1: "Request to invoke smart contract\n to transfer asset" -activate validator_1 -validator_1 -> ledger_1: "Invoke smart contract\n to transfer asset" -activate ledger_1 -ledger_1 -> ledger_1: "Send an escrow transaction\n (from: source account,\n to: escrow account)" -deactivate ledger_1 -validator_1 -->> verifier_1: "Request posted" -deactivate validator_1 -verifier_1 -->> routing_if: "Request posted" -deactivate verifier_1 -routing_if -->> business_lp: "Request posted" -deactivate business_lp -routing_if -->> user: "Request accepted" -deactivate routing_if - -/'** From: Ledger_1, To: Business_lp, Act: Notification(Escrow) **'/ -activate ledger_1 -ledger_1 -> ledger_1: "Consensus completed" -validator_1 <- ledger_1: "Notify new block data" -deactivate ledger_1 -activate validator_1 -validator_1 -> validator_1: "Validate transactions" -validator_1 -> validator_1: "digital sign on \nvalid transaction" -validator_1 -> verifier_1: "Request to update\n transaction status" -activate verifier_1 -verifier_1 -> verifier_1: "Validate digital signs" -verifier_1 -> routing_if: "Request to update\n transaction status" -activate routing_if -routing_if -> business_lp: "Request to update\n transaction status" -activate business_lp -business_lp -> business_lp: "Update transaction \nstatus(asset is escrowed)" -business_lp -->> routing_if: "transaction update\n accepted" -routing_if -->> verifier_1: "transaction update\n accepted" -deactivate routing_if -verifier_1 -->> validator_1: "transaction update\n accepted" -deactivate verifier_1 -deactivate validator_1 - -business_lp -> business_lp: "determine \nnext operation\n(transfer Quorum asset)" - -== Transfer Quorum asset == - -/'** From: Business_lp, To: Ledger_2, Act: Transfer transaction **'/ -business_lp -> routing_if: "Request to \ntransfer Quorum asset" -activate routing_if -routing_if -> verifier_2: "Request to \ntransfer Quorum asset" -activate verifier_2 -verifier_2 -> validator_2: "Request to \ntransfer Quorum asset" -activate validator_2 -validator_2 -> ledger_2: "Invoke smart contract\n to transfer asset" -activate ledger_2 -ledger_2 -> ledger_2: "Send a transfer transaction\n (from: exchanger account,\n to: destination account)" -deactivate ledger_2 -validator_2 -->> verifier_2: "Request posted" -deactivate validator_2 -verifier_2 -->> routing_if: "Request posted" -deactivate verifier_2 -routing_if -->> business_lp: "Request posted" -deactivate routing_if -deactivate business_lp - -/'** From: Ledger_2, To: Business_lp, Act: Notification(Transfer) **'/ -activate ledger_2 -ledger_2 -> ledger_2: "Consensus completed" -validator_2 <- ledger_2: "Notify new block data" -deactivate ledger_2 -activate validator_2 -validator_2 -> validator_2: "Validate transactions" -validator_2 -> validator_2: "digital sign on \nvalid transaction" -validator_2 -> verifier_2: "Request to update\n transaction status" -activate verifier_2 -verifier_2 -> verifier_2: "Validate digital signs" -verifier_2 -> routing_if: "Request to update\n transaction status" -activate routing_if -routing_if -> business_lp: "Request to update\n transaction status" -activate business_lp -business_lp -> business_lp: "Update transaction \nstatus(asset is escrowed)" -business_lp -->> routing_if: "transaction update\n accepted" -routing_if -->> verifier_2: "transaction update\n accepted" -deactivate routing_if -verifier_2 -->> validator_2: "transaction update\n accepted" -deactivate verifier_2 -deactivate validator_2 - -business_lp -> business_lp: "determine \nnext operation\n(Settle transfered \nEthereum asset)" - -== Settle transfered Ethereum asset == - -/'** From: Business_lp, To: Ledger_1, Act: Settling escrowed transaction **'/ -business_lp -> routing_if: "Request to invoke smart contract\n to settle escrowed asset" -activate routing_if -routing_if -> verifier_1: "Request to invoke smart contract\n to settle escrowed asset" -activate verifier_1 -verifier_1 -> validator_1: "Request to invoke smart contract\n to settle escrowed asset" -activate validator_1 -validator_1 -> ledger_1: "Invoke smart contract\n to settle escrowed asset" -activate ledger_1 -ledger_1 -> ledger_1: "Send an settling escrowed transaction\n (from: escrow account,\n to: exchanger account)" -deactivate ledger_1 -validator_1 -->> verifier_1: "Request posted" -deactivate validator_1 -verifier_1 -->> routing_if: "Request posted" -deactivate verifier_1 -routing_if -->> business_lp: "Request posted" -deactivate business_lp -deactivate routing_if - -/'** From: Ledger_1, To: Business_lp, Act: Notification(Settle escrowed) **'/ -activate ledger_1 -ledger_1 -> ledger_1: "Consensus completed" -validator_1 <- ledger_1: "Notify new block data" -deactivate ledger_1 -activate validator_1 -validator_1 -> validator_1: "Validate transactions" -validator_1 -> validator_1: "digital sign on \nvalid transaction" -validator_1 -> verifier_1: "Request to update\n transaction status" -activate verifier_1 -verifier_1 -> verifier_1: "Validate digital signs" -verifier_1 -> routing_if: "Request to update\n transaction status" -activate routing_if -routing_if -> business_lp: "Request to update\n transaction status" -activate business_lp -business_lp -> business_lp: "Update transaction \nstatus(asset is escrowed)" -business_lp -->> routing_if: "transaction update\n accepted" -routing_if -->> verifier_1: "transaction update\n accepted" -deactivate routing_if -verifier_1 -->> validator_1: "transaction update\n accepted" -deactivate verifier_1 -deactivate validator_1 - -business_lp -> business_lp: "determine \nnext operation\n(no more operation)" - -@enduml \ No newline at end of file diff --git a/whitepaper/use-case-examplecoin-pegged-to-bitcoin.puml b/whitepaper/use-case-examplecoin-pegged-to-bitcoin.puml deleted file mode 100644 index c0bb1f5c0d..0000000000 --- a/whitepaper/use-case-examplecoin-pegged-to-bitcoin.puml +++ /dev/null @@ -1,29 +0,0 @@ -@startuml ExampleCoin Pegged to Bitcoin - -title Hyperledger Cactus\nExampleCoin Pegged to Bitcoin - -skinparam sequenceArrowThickness 2 -skinparam roundcorner 20 -skinparam maxmessagesize 60 -skinparam sequenceParticipant underline - -frame "Total ExampleCoin Inventory" as teci #LightGray { - node "A) ExampleCoin Wallets" as ecw #LightGreen { - } -} - -frame "Total Bitcoin Inventory" as tbi #LightGray { - node "All other Bitcoin Wallets" as aobw #LightYellow { - } - node "B) ExampleCoin Peg Reserves Wallet" as ecprw #LightGreen { - } -} - -ecw <...> ecprw #Green -note on link -A and B equal in value because -B is backing the value of A so long -as the wallet holder is a trusted entity. -end note - -@enduml diff --git a/whitepaper/use-case-food-tracability-integration.puml b/whitepaper/use-case-food-tracability-integration.puml deleted file mode 100644 index bb97d6136d..0000000000 --- a/whitepaper/use-case-food-tracability-integration.puml +++ /dev/null @@ -1,53 +0,0 @@ -@startuml Food Traceability Integration - -title Hyperledger Cactus\nFood Traceability Integration - -skinparam sequenceArrowThickness 2 -skinparam roundcorner 5 -skinparam maxmessagesize 30 -skinparam sequenceParticipant underline - -top to bottom direction - -actor "Retailer Customer" as rc - -frame "Company A\n<>" as ca #LightGray { - node "Food Traceability Solution A\n<>" as ftsa #LightYellow { - } -} - -frame "Company B\n<>" as cb #LightGray { - node "Food Traceability Solution B\n<>" as ftsb #LightYellow { - } -} - -frame "Food Retailer\n<>" as re #LightGray { - node "Food Traceability Solution B\n<>" as lftsb #LightGreen { - } - node "Integration for End to End Food Traceability\n<>" as ifeteft #LightSkyBlue { - } -} - -frame "Food Manufacturer\n<>" as fm #LightGray { - node "Food Traceability Solution A\n<>" as lftsa #LightGreen { - } -} - -frame "System Integrator Company\n<>" as sic #LightGray { - node "System Integration\n<>" as ssi { - } -} - -frame "Hyperledger\n<>" as hl #LightGray { - node "Hyperledger Cactus\n<>" as cactus #LightYellow { - } -} - -fm ==> ca #Green: Purchase Food Traceability Solution A -re ==> fm: Source food from manufacturer -re ==> cb #Green: Purchase Food Traceability Solution B -re ==> sic: Purchase System Integration Project -rc ==> ifeteft: Traces food origins -sic ==> hl: Builds integration on top of Hyperledger Cactus - -@enduml diff --git a/whitepaper/use-case-sequence-diagram-blockchain-migration.png b/whitepaper/use-case-sequence-diagram-blockchain-migration.png deleted file mode 100644 index be288cd061..0000000000 Binary files a/whitepaper/use-case-sequence-diagram-blockchain-migration.png and /dev/null differ diff --git a/whitepaper/use-case-sequence-diagram-blockchain-migration.puml b/whitepaper/use-case-sequence-diagram-blockchain-migration.puml deleted file mode 100644 index a63de0053b..0000000000 --- a/whitepaper/use-case-sequence-diagram-blockchain-migration.puml +++ /dev/null @@ -1,122 +0,0 @@ -@startuml -skinparam ArrowFontStyle italic - -title Hyperledger Cactus\nSequence Diagram - Blockchain Migration - -actor Consortium_Member_A as a -actor Consortium_Member_B as b - -box Cactus -entity "API" as api -entity "Validator(s)" as v -end box - -box "Ledgers" -database Ledger1 as d1 -database Ledger2 as d2 -end box - -autoactivate on -== Agreement Phase == -a -> b: Propose Blockchain Migration -Note right -Off-chain procedure -end note - return Send Endorsement - -a -> api: Sign Transaction to Endorse Blockchain Migration -return Request Confirmed - - -b -> api: Sign Transaction to Endorse Blockchain Migration -return Request Confirmed - - -autoactivate off -api -> a: Ready to Proceed -api -> b: Ready to Proceed -autoactivate on - -== Initialization Phase == -a -> api: Sign Transaction to Initialize Blockchain Migration - api -> v: Deploy Interoperability Support Data\n(smart contracts and configuration files) on Ledger1 - v -> d1: Deploy Support Data as Consortium_Member_A - return Data Deployed - return Data Deployed -return Ready to Initiate Migration - -b -> api: Sign Transaction to Initialize Blockchain Migration - api -> v: Deploy Interoperability Support Data on Ledger1 - v -> d1: Deploy Support Data as Consortium_Member_B - return Data Deployed - return Data Deployed -return Ready to Initiate Migration - -a -> api: Initialize Blockchain Migration - api -> v: Initialize Consortium_Member_A's view\non exisitng assets and data - v -> d1: Query Ledger 1 as Consortium_Member_A - return Return Results - return Return results - return Initialize Blockchain Migration Success - autoactivate off - api -> api: **processes query and builds Consortium_Member_A's**\n**view on existing assets and data** - return -api -> a: Send Consortium_Member_A's view on L1 -a -> api: Confirm View -return OK -autoactivate on - -b -> api: Initialize Blockchain Migration - api -> v: Initialize Consortium_Member_B's view\non exisitng assets and data - v -> d1: Query Ledger 1 as Consortium_Member_B - return Return Results - return Return results - return Initialize Blockchain Migration Success - autoactivate off - api -> api: **processes query and builds Consortium_Member_B's**\n**view on existing assets and data** - return -api -> b: Send Consortium_Member_B's view on L1 -b -> api: Confirm View -return OK - - - - -api -> api: Merge views -Note right -Optional: This process merges the views of -Consortium_Member_A and Consortium_Member_B -into a consolidated view -end note -return -autoactivate on -api -> a: Merged View -return Accept merge - -api -> b: Merged View -return Accept merge - - -== Migration Phase == -a -> api: initiate Blockchain Migration - api -> v: Execute Migration to Ledger 2 - v -> d2: Execute transactions\non Ledger 2 as Consortium_Member_A - return Transactions Successfully Executed - return Success -return Success - - - -b -> api: initiate Blockchain Migration - api -> v: Execute Migration to Ledger 2 - v -> d2: Execute transactions\non Ledger 2 as Consortium_Member_B - return Transactions Successfully Executed - return Success -return Success - - -autoactivate off -api -> api: **Perform final adjustments, e.g., submit**\n**missing transactions** -api -> a: Migration Process Completed -api -> b: Migration Process Completed -@enduml \ No newline at end of file diff --git a/whitepaper/use-case-sequence-diagram-end-user-wallet-authentication-authorization.png b/whitepaper/use-case-sequence-diagram-end-user-wallet-authentication-authorization.png deleted file mode 100644 index b17ee26d25..0000000000 Binary files a/whitepaper/use-case-sequence-diagram-end-user-wallet-authentication-authorization.png and /dev/null differ diff --git a/whitepaper/use-case-sequence-diagram-end-user-wallet-authentication-authorization.puml b/whitepaper/use-case-sequence-diagram-end-user-wallet-authentication-authorization.puml deleted file mode 100644 index 53726fa98e..0000000000 --- a/whitepaper/use-case-sequence-diagram-end-user-wallet-authentication-authorization.puml +++ /dev/null @@ -1,78 +0,0 @@ -@startuml Sequence Diagram - End User Wallet Authentication Authorization - -skinparam ArrowFontStyle italic - -title Hyperledger Cactus\nSequence Diagram - End User Wallet Authentication Authorization - -actor User_A as a <> - -box Cactus #White -entity "API" as api -entity "Validator(s)" as v -database "Keychain" as k -end box - -box "Ledgers" #White -database LedgerOne as d1 -database LedgerTwo as d2 -end box - -autoactivate on -autonumber - -== Register with Hyperledger Cactus == - -a -> api: Register User Account -return Bearer Token - -== Import PKI == - -a -> api: Import **LedgerOne** keypair - api -> k: Store **LedgerOne** keypair\nencrypted at rest - return Keychain Update Done -return Import Keypair Done - -a -> api: Import **LedgerTwo** keypair - api -> k: Store **LedgerTwo** keypair\nencrypted at rest - return Keychain Update Done -return Import Keypair Done - -== Transact on Ledgers == - -a -> api: Execute Transaction\non **LedgerOne** -note right -**User A** only need to present -**Bearer Token** from step -2 and Hyperledger Cactus will be able to -impersonate **User A** -on LedgerOne -end note - api -> v: Execute Transaction\non **LedgerOne** - - v -> k: Fetch LedgerOne\nPrivate Key of User_A - return Private Key - - v -> d1: Execute Transaction\non **LedgerOne**\nas **User_A** - return Transaction Executed - return Transaction Executed -return Transaction Executed - -a -> api: Execute Transaction\non **LedgerTwo** -note right -**User A** only need to present -**Bearer Token** from step -2 and Hyperledger Cactus will be able to -impersonate **User A** -on LedgerTwo -end note - api -> v: Execute Transaction\non **LedgerTwo** - - v -> k: Fetch LedgerTwo\nPrivate Key of User_A - return Private Key - - v -> d2: Execute Transaction\non **LedgerTwo**\nas **User_A** - return Transaction Executed - return Transaction Executed -return Transaction Executed - -@enduml diff --git a/whitepaper/use-case-sequence-diagram-escrowed-sale-of-data-for-coins.puml b/whitepaper/use-case-sequence-diagram-escrowed-sale-of-data-for-coins.puml deleted file mode 100644 index 2c13c3fc4a..0000000000 --- a/whitepaper/use-case-sequence-diagram-escrowed-sale-of-data-for-coins.puml +++ /dev/null @@ -1,39 +0,0 @@ -@startuml Sequence Diagram - Escrowed Sale of Data for Coins - -skinparam ArrowFontStyle italic - -title Hyperledger Cactus\nSequence Diagram - Escrowed Sale of Data for Coins - -actor User_A as a -actor User_B as b - -box Cactus -entity "API" as api -end box - -box "Ledgers" -database Fabric_Ledger as d1 -database Besu_Ledger as d2 -end box - -autoactivate on - -a -> api: Propose Transaction -return Transaction Proposal Created - -a -> api: Sign Transaction to Escrow Funds - api -> d2: Send Funds to Escrow - return Escrow Transaction Confirmed -return Escrow Transaction Confirmed - -b -> api: Sign Transaction to Escrow Data - api -> d1: Send Data to Escrow - return Escrow Transaction Confirmed -return Escrow Transaction Confirmed - -autoactivate off -api -> api: **Release funds and data**\n**to receiving parties**\n**User A and B respectively** -api -> a: Transaction Completed -api -> b: Transaction Completed - -@enduml diff --git a/whitepaper/use-case-sequence-diagram-fabric-quorum-asset-transfer.puml b/whitepaper/use-case-sequence-diagram-fabric-quorum-asset-transfer.puml deleted file mode 100644 index 18eb938598..0000000000 --- a/whitepaper/use-case-sequence-diagram-fabric-quorum-asset-transfer.puml +++ /dev/null @@ -1,69 +0,0 @@ -@startuml Sequence Diagram - Fabric Quorum Asset Transfer - -title Hyperledger Cactus\nSequence Diagram - Fabric Quorum Asset Transfer - -actor User_A as a - -box "Hyperledger Cactus" #LightGray -entity "API Server" as apis -entity "Validator" as v -end box - -box "Ledgers" -entity Cactus_Contract_Fabric as c1 -entity Cactus_Contract_Quorum as c2 -database Fabric_Ledger as d1 -database Quorum_Ledger as d2 -end box - -autoactivate on - -== Authenticate == - -a -> apis: Authenticate -return Auth. Token - -== Lock Fabric Asset == - -a -> apis: Lock Fabric Asset - - apis -> v: Lock Fabric Asset - v -> c1: Invoke Contract: Lock Fabric Asset - c1 -> d1: Write to Ledger State \n(Asset.locked=true) - return Ledger Updated OK - return Locked Fabric Asset - return Locked Fabric Asset -return Locked Fabric Asset - -autoactivate off -a -> a: Verify Signatures\nof Hyperledger Cactus Validators -opt Signatures Valid - a -> a: Proceed with Execution -else Signatures Invalid - a -> a: Abort Process,\npossible MITM\nattack in progress -end -autoactivate on - -== Create Quorum Asset == - -a -> apis: Create Quorum Asset - - apis -> v: Create Quorum Asset - - autoactivate off - v -> v: Verify Signatures\nof Hyperledger Cactus Validators - critical Signatures Valid - v -> v: Continue - else Signatures Invalid - v -> v: Abort - end - autoactivate on - - v -> c2: Invoke Contract: Create Asset - c2 -> d2: Write Asset to Ledger State - return Ledger Updated OK - return Quorum Asset, Metadata - return Quorum Asset, Metadata -return Quorum Asset, Metadata - -@enduml diff --git a/whitepaper/use-case-sequence-diagram-food-traceability-integration.puml b/whitepaper/use-case-sequence-diagram-food-traceability-integration.puml deleted file mode 100644 index 3fa6094e6c..0000000000 --- a/whitepaper/use-case-sequence-diagram-food-traceability-integration.puml +++ /dev/null @@ -1,100 +0,0 @@ -@startuml Sequence Diagram - Food Traceability Integration - -skinparam ArrowFontStyle italic - -title Hyperledger Cactus\nSequence Diagram - Food Traceability Integration - -actor User_A as a <> -actor User_B as b <> -actor User_C as c <> - -box Application #White -entity "Frontend" as frontend -entity "Backend" as backend -end box - -box Cactus #White -entity "API" as api -entity "Validator(s)" as v -end box - -box "Ledgers" #White -database Food_Ledger_1 as d1 -database Food_Ledger_2 as d2 -end box - -autoactivate on - -== Record Data == - -b -> frontend: Append Food Data Record - frontend -> backend: Append Food Data Record - backend -> api: Append Food Data Record - api -> d1: Append Food Data Record - return Food Data Record Appended - return Food Data Record Appended - return Food Data Record Appended -return Food Data Record Appended - -c -> frontend: Append Food Data Record - frontend -> backend: Append Food Data Record - backend -> api: Append Food Data Record - api -> d2: Append Food Data Record - return Food Data Record Appended - return Food Data Record Appended - return Food Data Record Appended -return Food Data Record Appended - -== Merge Data == - -loop Polling/Triggered - backend -> api: Query Ledger 1 - api -> d1: Query Ledger 1 - return Food Record on Ledger 1 - return Food Record on Ledger 1 - - backend -> api: Query Ledger 2 - api -> d2: Query Ledger 2 - return Food Record on Ledger 2 - return Food Record on Ledger 2 - - backend -> backend: Compute Data Diff Ledger 1 - return Data Diff Ledger 1 - backend -> api: Append Missing Data to Ledger 1 - api -> d1: Append Missing Data to Ledger 1 - return Ledger 1 Updated - return Ledger 1 Updated - - backend -> backend: Compute Data Diff Ledger 2 - return Data Diff Ledger 2 - backend -> api: Append Missing Data to Ledger 2 - api -> d2: Append Missing Data to Ledger 2 - return Ledger 2 Updated - return Ledger 2 Updated - -end loop - -== Trace Food Origins == - -a -> frontend: Query Food Merged Record - frontend -> backend: Query Food Merged Record - backend -> api: Query Food Merged Record - api -> d1: Query Food Merged Record - return Merged Food Data Records - note left - At this point the data on - Food Ledger 1 and 2 should - be equivalent and therefore - any one of them can be - queried by Hyperledger Fabric - to obtain the complete food - trace records. - end note - return Merged Food Data Records - return Merged Food Data Records -return Merged Food Data Records - -a -> a: Make well informed\npurchasing decision\nbased on food origins. - - -@enduml diff --git a/whitepaper/use-case-sequence-diagram-healthcare-data-sharing-with-acl.puml b/whitepaper/use-case-sequence-diagram-healthcare-data-sharing-with-acl.puml deleted file mode 100644 index 6af0456a09..0000000000 --- a/whitepaper/use-case-sequence-diagram-healthcare-data-sharing-with-acl.puml +++ /dev/null @@ -1,46 +0,0 @@ -@startuml Sequence Diagram - Healthcare Data Sharing with Access Control Lists - -skinparam ArrowFontStyle italic - -title Hyperledger Cactus\nSequence Diagram - Healthcare Data Sharing with Access Control Lists - -actor User_A as a <> -actor User_B as b <> - -box Cactus #WhiteSmoke -entity "API" as api -entity "Validator(s)" as v -end box - -box "Ledgers" #WhiteSmoke -database Fabric_Ledger as d1 -database Besu_Ledger as d2 -end box - -autoactivate on - -b -> api: Request Data Access - - api -> a: Prompt for Data Access - return Grant Permission - - api -> d2: Get Asset\n<> - return Asset\n<> - - autoactivate off - api -> v: Verify Asset\n<> - critical Signatures Valid - v -> api: Proceed - else Signatures Invalid - v -> api: Abort - end - autoactivate on - - api -> v: Create Asset\n<> - v -> d1: Create Asset\n<> - return Asset Created OK\n<> - return Asset Created OK\n<> - -return Data Access Granted - -@enduml diff --git a/whitepaper/whitepaper.md b/whitepaper/whitepaper.md index 5729c94a04..e549f91bce 100644 --- a/whitepaper/whitepaper.md +++ b/whitepaper/whitepaper.md @@ -1,1735 +1,28 @@ - + +--- -# Hyperledger Cactus
Whitepaper +# Hyperledger Cacti
Whitepaper -## Version 0.2 +## Version 2.0 Photo by Pontus Wellgraf on Unsplash -
- -# Contributors - -| Contributors/Reviewers | Email | -|--------------------------------|-------------------------------------------| -| Hart Montgomery | hmontgomery@us.fujitsu.com | -| Hugo Borne-Pons | hugo.borne-pons@accenture.com | -| Jonathan Hamilton | jonathan.m.hamilton@accenture.com | -| Mic Bowman | mic.bowman@intel.com | -| Peter Somogyvari | peter.somogyvari@accenture.com | -| Shingo Fujimoto | shingo_fujimoto@fujitsu.com | -| Takuma Takeuchi | takeuchi.takuma@fujitsu.com | -| Tracy Kuhrt | tracy.a.kuhrt@accenture.com | -| Rafael Belchior | rbelchior@blockdaemon.com | - -# Document Revisions - -| Date of Revision | Description of Changes Made | -|-----------------------|--------------------------------------------------------| -| March 2022 | Abstract, theoretical framework draft | -| February 2020 | Initial draft | - - -
- -- [1. Abstract](#1-abstract) -- [2. Introduction to Blockchain Interoperability](#2-introduction-to-blockchain-interoperability) - - [2.2 Interoperability mode](#22-interoperability-mode) - - [2.3 Connection mode](#23-connection-mode) - - [2.4 Blockchain Interoperability Solution Types](#24-blockchain-interoperability-solution-types) - - [2.5 Blockchain Interoperability Design Patterns](#25-blockchain-interoperability-design-patterns) - - [2.6 General Workflow to Build a cross-chain decentralized application](#26-general-workflow-to-build-a-cross-chain-decentralized-application) -- [3. Example Use Cases](#3-example-use-cases) - - [3.1 Asset Trade](#31-asset-trade) - - [3.2 Electricity Trade](#32-electricity-trade) - - [3.3 Supply chain](#33-supply-chain) - - [3.4 Ethereum to Quorum Asset Transfer](#34-ethereum-to-quorum-asset-transfer) - - [3.5 Escrowed Sale of Data for Coins](#35-escrowed-sale-of-data-for-coins) - - [3.6 Money Exchanges](#36-money-exchanges) - - [3.7 Stable Coin Pegged to Other Currency](#37-stable-coin-pegged-to-other-currency) - - [3.7.1 With Permissionless Ledgers (BTC)](#371-with-permissionless-ledgers-btc) - - [3.7.2 With Fiat Money (USD)](#372-with-fiat-money-usd) - - [3.8 Healthcare Data Sharing with Access Control Lists](#38-healthcare-data-sharing-with-access-control-lists) - - [3.9 Integrate Existing Food Traceability Solutions](#39-integrate-existing-food-traceability-solutions) - - [3.10 End User Wallet Authentication/Authorization](#310-end-user-wallet-authenticationauthorization) - - [3.11 Blockchain Migration](#311-blockchain-migration) - - [3.11.1 Blockchain Data Migration](#3111-blockchain-data-migration) - - [3.11.2 Blockchain Smart Contract Migration](#3112-blockchain-smart-contract-migration) - - [3.11.3 Semi-Automatic Blockchain Migration](#3113-semi-automatic-blockchain-migration) -- [4. Software Design](#4-software-design) - - [4.1. Principles](#41-principles) - - [4.1.1. Wide support](#411-wide-support) - - [4.1.2. Plugin Architecture from all possible aspects](#412-plugin-architecture-from-all-possible-aspects) - - [4.1.3. Prevent Double spending Where Possible](#413-prevent-double-spending-where-possible) - - [4.1.4 DLT Feature Inclusivity](#414-dlt-feature-inclusivity) - - [4.1.5 Low impact](#415-low-impact) - - [4.1.6 Transparency](#416-transparency) - - [4.1.7 Automated workflows](#417-automated-workflows) - - [4.1.8 Default to Highest Security](#418-default-to-highest-security) - - [4.1.9 Transaction Protocol Negotiation](#419-transaction-protocol-negotiation) - - [4.1.10 Avoid modifying the total amount of digital assets on any blockchain whenever possible](#4110-avoid-modifying-the-total-amount-of-digital-assets-on-any-blockchain-whenever-possible) - - [4.1.11 Provide abstraction for common operations](#4111-provide-abstraction-for-common-operations) - - [4.1.12 Integration with Identity Frameworks (Moonshot)](#4112-integration-with-identity-frameworks-moonshot) - - [4.2 Feature Requirements](#42-feature-requirements) - - [4.2.1 New Protocol Integration](#421-new-protocol-integration) - - [4.2.2 Proxy/Firewall/NAT Compatibility](#422-proxyfirewallnat-compatibility) - - [4.2.3 Bi-directional Communications Layer](#423-bi-directional-communications-layer) - - [4.2.4 Consortium Management](#424-consortium-management) - - [4.3 Working Policies](#43-working-policies) -- [5. Architecture](#5-architecture) - - [5.1 Deployment Scenarios](#51-deployment-scenarios) - - [5.1.1 Production Deployment Example](#511-production-deployment-example) - - [5.1.2 Low Resource Deployment Example](#512-low-resource-deployment-example) - - [5.2 System architecture and basic flow](#52-system-architecture-and-basic-flow) - - [5.2.1 Definition of key components in system architecture](#521-definition-of-key-components-in-system-architecture) - - [5.2.2 Bootstrapping Cactus application](#522-bootstrapping-cactus-application) - - [5.2.3 Processing Service API call](#523-processing-service-api-call) - - [5.3 APIs and communication protocols between Cactus components](#53-apis-and-communication-protocols-between-cactus-components) - - [5.3.1 Cactus Service API](#531-cactus-service-api) - - [Open Endpoints](#open-endpoints) - - [Restricted Endpoints](#restricted-endpoints) - - [5.3.2 Ledger plugin API](#532-ledger-plugin-api) - - [5.3.3 Exection of "business logic" at "Business Logic Plugin"](#533-exection-of-business-logic-at-business-logic-plugin) - - [5.4 Technical Architecture](#54-technical-architecture) - - [5.4.1 Monorepo Packages](#541-monorepo-packages) - - [5.4.1.1 cmd-api-server](#5411-cmd-api-server) - - [5.4.1.1.1 Runtime Configuration Parsing and Validation](#54111-runtime-configuration-parsing-and-validation) - - [5.4.1.1.2 Configuration Schema - API Server](#54112-configuration-schema---api-server) - - [5.4.1.1.3 Plugin Loading/Validation](#54113-plugin-loadingvalidation) - - [5.4.1.2 core-api](#5412-core-api) - - [5.4.1.3 API Client](#5413-api-client) - - [5.4.1.4 keychain](#5414-keychain) - - [5.4.1.5 tracing](#5415-tracing) - - [5.4.1.6 audit](#5416-audit) - - [5.4.1.7 document-storage](#5417-document-storage) - - [5.4.1.8 relational-storage](#5418-relational-storage) - - [5.4.1.9 immutable-storage](#5419-immutable-storage) - - [5.4.2 Deployment Diagram](#542-deployment-diagram) - - [5.4.3 Component Diagram](#543-component-diagram) - - [5.4.4 Class Diagram](#544-class-diagram) - - [5.4.5 Sequence Diagram - Transactions](#545-sequence-diagram---transactions) - - [5.5 Transaction Protocol Specification](#55-transaction-protocol-specification) - - [5.5.1 Handshake Mechanism](#551-handshake-mechanism) - - [5.5.2 Transaction Protocol Negotiation](#552-transaction-protocol-negotiation) - - [5.6 Plugin Architecture](#56-plugin-architecture) - - [5.6.1 Ledger Connector Plugins](#561-ledger-connector-plugins) - - [5.6.1.1 Ledger Connector Besu Plugin](#5611-ledger-connector-besu-plugin) - - [5.6.1.2 Ledger Connector Connector Corda](#5612-ledger-connector-connector-corda) - - [5.6.1.3 Ledger Connector Fabric Socketio](#5613-ledger-connector-fabric-socketio) - - [5.6.1.4 Ledger Connector Fabric Plugin](#5614-ledger-connector-fabric-plugin) - - [5.6.1.5 Ledger Connector Go Ethereum Socketio](#5615-ledger-connector-go-ethereum-socketio) - - [5.6.1.6 Ledger Connector Iroha Plugin](#5616-ledger-connector-iroha-plugin) - - [5.6.1.7 Ledger Connector Quorum Plugin](#5617-ledger-connector-quorum-plugin) - - [5.6.1.8 Ledger Connector Sawtooth Socketio Plugin](#5618-ledger-connector-sawtooth-socketio-plugin) - - [5.6.1.9 Ledger Connector Xdai Plugin](#5619-ledger-connector-xdai-plugin) - - [5.6.2 HTLCs Plugins](#562-htlcs-plugins) - - [5.6.2.1 HTLC-ETH-Besu Plugin](#5621-htlc-eth-besu-plugin) - - [5.6.2.2 HTLC-ETH-ERC20-Besu Plugin](#5622-htlc-eth-erc20-besu-plugin) - - [5.6.3 Identity Federation Plugins](#563-identity-federation-plugins) - - [5.6.3.1 X.509 Certificate Plugin](#5631-x509-certificate-plugin) - - [5.6.4 Key/Value Storage Plugins](#564-keyvalue-storage-plugins) - - [5.6.5 Serverside Keychain Plugins](#565-serverside-keychain-plugins) - - [5.6.6 Manual Consortium Plugin](#566-manual-consortium-plugin) - - [5.6.7 Test Tooling](#567-test-tooling) -- [6. Identities, Authentication, Authorization](#6-identities-authentication-authorization) - - [6.1 Definition of Identities in Cactus](#61-definition-of-identities-in-cactus) - - [6.2 Transaction Signing Modes, Key Ownership](#62-transaction-signing-modes-key-ownership) - - [6.2.1 Client-side Transaction Signing](#621-client-side-transaction-signing) - - [6.2.2 Server-side Transaction Signing](#622-server-side-transaction-signing) - - [6.3 Open ID Connect Provider, Identity Provider](#63-open-id-connect-provider-identity-provider) - - [6.4 Server-side Keychain for Web Applications](#64-server-side-keychain-for-web-applications) -- [7. Terminology](#7-terminology) -- [8. Related Work](#8-related-work) -- [9. References](#9-references) -- [10. Recommended Reference](#10-recommended-reference) - -
- -# 1. Abstract - -"Before a technology unlocks its full range of applications, it first undergoes underestimation. Distributed Ledger Technology (DLT), including blockchain, is no exception and is here to stay". -Hundreds of blockchains exist, supporting diverse use cases: from cryptocurrencies, to digital identity, supply chain, and education certification. The trends towards using blockchain for those are increasing. A recent report from Gartner predicts that by 2023, 35% of enterprise -blockchain applications will integrate with decentralized applications and services. Many blockchain ecosystems. Blockchain is slowly but steadily becoming an infrastructure for global value exchange and distributed computation" [[6](#8-references)]. - - - -It allows communication between systems to exchange data and digital assets, leading to more diverse and innovative solutions to real-world problems. It allows synergies across ecosystems and leverages network effects, leading to a similar boom that the rise of the Internet has seen. This way, no blockchain should become a single point of failure, and we contribute directly to the decentralization of the technology. - -However, most blockchains were not createed with interoperability in mind, being standalone networks. Connecting those efficiently and securely remains an open problem. - - - -Hyperledger Cactus is an open-source project connecting distributed ledgers to enterprise systems via a set of plugins. Plugins can be _business logic plugins_, _connector plugins_, _tooling plugins_, or _core packages_. Business logic plugins implement cross-chain use cases (e.g., asset exchange across DLTs). Connector plugins implement blockchain clients, allowing Cactus nodes to connect to blockchains (e.g., Hyperledger Fabric connector). Tooling plugins support the development of business logic plugins (e.g., cryptography plugins, storage plugins). Core packages support the creation of Cactus nodes and their consortia (e.g., cactus-core). - -Cactus is blockchain-agnostic and provides a modular architecture for bespoke cross-chain business logic to be deployed on multiple heterogeneous blockchain infrastructures. Cactus then aims to be the foundation of mature blockchain ecosystems by directly supporting businessses that are inherently multi-system. By integrating blockchains with other systems in a systematic and unified approach, Cactus minimizes security risks. - -Cactus also introduces an innovation on the space: the possibility to run decentralized cross-chain use cases by leveraging a consortium Cactus nodes. Current efforts are on studying this scheme from an academic perspective. - -# 2. Introduction to Blockchain Interoperability - -This section acts as a building block to describe the different key components of blockchain interoperability: the problem of interoperability, interoperability mode, connection mode, and solution type. - -Interoperating blockchains imply two fundamental problems: -1) how to represent internal state to third-party blockchains, and 2) how to guarantee that business logic operating in multiple blockchains is sound. - -The first point is important so the interoperation system can act upon reliable and up-to-date data. The second point depends on the specific cross-chain use case to be implemented. For instance, if the cross-chain use case is a bridge, then cross-chain double spend must be avoided. - - -## 2.2 Interoperability mode - - -The interoperability mode answers the “what” question: what is the artifact managed by the blockchain -interoperability solution. Modes are (based on [[6](#8-references)]): - - -1. Data Transfer: data is copied from one DLT to another, with an optional intermediate processing step. For example, copying price information from one DLT into another. Data can be copied from one ledger to the other (typically no cross-chain conditions are implied in data transfers) - -2. Asset Transfer: unilateral or bilateral asset transfers. Assets are transferred from one DLT -network to another (implies burning or locking the asset on the source DLT network). For example, locking Bitcoin to a multi-signature address on the bitcoin -blockchain and minting a representative asset on the Ethereum blockchain. - -3. Asset Exchange: atomic asset transfers. Assets are exchanged in their respective DLT network, -i.e., no transfers across DLT networks occur. Participants need to be present in both chains -for this exchange to happen. For example, using hash time lock contracts. - -Assets typically imply cross-chain logic to preserve their value in both source and target chains. Asset types include fungible assets (value token/coin) non-fungibles assets (non dividable assets). A fungible asset is an asset that can be used interchangeably with another asset of the same type, like a currency. For example, a 1 USD bill can be swapped for any other 1 USD bill. Cryptocurrencies, such as ETH (Ether) and BTC (Bitcoin), are FAs. A non-fungible asset is an asset that cannot be swapped as it is unique and has specific properties. For example, a car is a non-fungible asset as it has unique properties, such as color and price. CryptoKitties are NFAs as well. There are two standards for fungible and non-fungible assets on the Ethereum network (ERC-20 Fungible Token Standard and ERC-721 Non-Fungible Token Standard). - -Unicity applies to FAs and NFAs meaning it guarantees that only one valid representation of a given asset exists in the system. It prevents double-spending of the same token/coin in different blockchains. The same data package can have several representations on different ledgers while an asset (FA or NFA) can have only one representation active at any time, i.e., an asset exists only on one blockchain while it is locked/burned on all other blockchains. If fundamental disagreement persists in the community about the purpose or operational upgrades of a blockchain, a hard fork can split a blockchain creating two representations of the same asset to coexist. For example, Bitcoin split into Bitcoin and Bitcoin Cash in 2017. Forks are not addressing blockchain interoperability so the definition of unicity applies in a blockchain interoperability context. A data package that was once created as a copy of another data package might divert from its original one over time because different blockchains might execute different state changes on their data packages. - - -## 2.3 Connection mode - -There are three methods for a dApp or mdApp to connect to a DLT. -These mechanisms are called the connection modes. Those are: - -1. DLT Nodes: DLT nodes are the software systems that run a DLT protocol. - -2. DLT Proxy: "a DLT node proxy manages the routing and load balancing issues between -an application and one or more DLT nodes, creating logical separation. To an application, -interacting with a DLT node proxy is nearly identical to interacting with a DLT node as the -message requests and responses will be virtually the same. The only possible difference may -be identifying metadata in the messages to track the DLT node proxy users (e.g., for rate -limiting reasons)". [[6](#8-references)] - -3. DLT Gateways: Like a DLT node proxy, a DLT gateway also manages the routing and load -balancing issues between an application and one or more DLT nodes, creating logical separation. Example: Polkadot’s block explorer; Self-hosted ODAP gateways; Quant Network’s -Overledger. [[6](#8-references)] - -## 2.4 Blockchain Interoperability Solution Types - -Please refer to [[5](#8-references)] or [[6](#8-references)] for a comprehensive and systematic taxonomies. - - -## 2.5 Blockchain Interoperability Design Patterns - -* Ledger transfer: - -An asset gets locked/burned on one blockchain and then a representation of the same asset gets released in the other blockchain[e](#22-footnotes-introduction). There are never two representations of the same asset alive at any time. Data is an exception since the same data can be transferred to several blockchains. There are one-way or two-way ledger transfers depending on whether the assets can be transferred only in one direction from a source blockchain to a destination blockchain or assets can be transferred in and out of both blockchains with no designated source blockchain and destination blockchain. - - -* Atomic swap[f](#22-footnotes-introduction): - -A write transaction is performed on Blockchain A concurrently with another write transaction on blockchain B. There is no asset/data/coin leaving any blockchain environment. The two blockchain environments are isolated but, due to the blockchain interoperability implementation, both transactions are committed atomically. That means either both transactions are committed successfully or none of the transactions are committed successfully. - - -* Ledger interaction[f](#22-footnotes-introduction): - -An action[g](#22-footnotes-introduction) happening on Blockchain A is causing an action on Blockchain B. The state of Blockchain A causes state changes on Blockchain B. There are one-way or two-way ledger interactions depending on whether only the state of one of the blockchains can affect the state on the other blockchain or both blockchain states can affect state changes on the corresponding other blockchain. - - -* Ledger entry point coordination: - -This blockchain interoperability type concerns end-user wallet authentication/ authorization enabling read and write operations to independent ledgers from one single entry point. Any read or write transaction submitted by the client is forwarded to the corresponding blockchain and then committed/executed as if the blockchain would be operate on its own. - - -The ledger transfer has a high degree of interference between the blockchains since the livelihood of a blockchain can be reduced in case too many assets are locked/burned in a connected blockchain. The ledger interaction has a high degree of interference between the blockchains as well since the state of one blockchain can affect the state of another blockchain. Atomic swaps have less degree of interference between the blockchains since all assets/data stay in their respective blockchain environment. The ledger entry point coordination has no degree of interference between the blockchains since all transactions are forwarded and executed in the corresponding blockchain as if the blockchains would be operated in isolation. - - - - - -
Figure description: One-way ledger transfer - -
Figure description: Two-way ledger transfer - -
Figure description: Atomic swap - -
Figure description: Ledger interaction - -
Figure description: Ledger entry point coordination - - - - -Legend: - -![](https://render.githubusercontent.com/render/math?math=O_1=) Object 1 - -![](https://render.githubusercontent.com/render/math?math=O_1^{begin}=) State of object *O1* at the beginning of transaction - -![](https://render.githubusercontent.com/render/math?math=O_2^{begin}=) State of object *O2* at the beginning of transaction - -![](https://render.githubusercontent.com/render/math?math=O_1^{end}=) State of object *O1* at the end of transaction - -![](https://render.githubusercontent.com/render/math?math=O_2^{end}=) State of object *O2* at the end of transaction - -*O1end* = Representation of object *O1* at the end of transaction in another blockchain - -*O2end* = Representation of object } *O2* at the end of transaction in another blockchain - -![](https://render.githubusercontent.com/render/math?math=T_1=) Transaction 1 - -![](https://render.githubusercontent.com/render/math?math=T_2=) Transaction 2 - -*T1* = Representation of transaction 1 (T1) in another blockchain - -*T1* = Representation of transaction 2 (T2) in another blockchain - -![](https://render.githubusercontent.com/render/math?math=E_1=) Event 1 - -![](https://render.githubusercontent.com/render/math?math=E_2(O_1||T_1||E_1)=) Event 2 depends on *O1* or *T1* or *E1* - -![](https://render.githubusercontent.com/render/math?math=T_2(O_1||T_1||E_1)=) Transaction 2 depends on *O1* or *T1* or *E1* - - - -* Burning or Locking of Assets - - -To guarantee unicity, an asset (NFA or FA) has to be burned or locked before being transferred into another blockchain. Locked assets can be unlocked in case the asset is retransferred back to its original blockchain, whereas the burning of assets is an irreversible process. It is worth noting that locking/burning of assets is happening during a ledger transfer but can be avoided in use cases where both parties have wallets/accounts on both ledgers by using atomic swaps instead. Hence, most cryptocurrency exchange platforms rely on atomic swaps and do not burn FAs. For example, ordinary coins, such as Bitcoin or Ethereum, can only be generated by mining a block. Therefore, Bitcoin or Ethereum exchanges have to rely on atomic swaps rather than two-way ledger transfers because it is not possible to create BTC or ETH on the fly. In contrast, if the minting process of an FA token can be leveraged on during a ledger transfer, burning/locking of an asset becomes a possible implementation option, such as in the ETH token ledger transfer from the old PoW chain (Ethereum 1.0) to the PoS chain (aka Beacon Chain in Ethereum 2.0). Burning of assets usually applies more to tokens/coins (FAs) and can be seen as a donation to the community since the overall value of the cryptocurrency increases. - -Burning of assets can be implemented as follows: - -1. Assets are sent to the address of the coinbase/generation transaction[h](#22-footnotes-introduction) in the genesis block. A coinbase/generation transaction is in every block of blockchains that rely on mining. It is the address where the reward for mining the block is sent to. Hence, this will burn the tokens/coins in the address of the miner that mined the genesis block. In many blockchain platforms, it is proven that nobody has the private key to this special address. - -2. Tokens/Coins are subtracted from the user account as well as optionally from the total token/coin supply value. - - -## 2.6 General Workflow to Build a cross-chain decentralized application -Cactus streamlines the development of cross-chain decentralized application, also known as multiple DLT apps (mDapps) by having three major pilars: 1) robust testing infrastructure (tooling plugins), 2) a modular architecture -enabling to combine plugins according to each use case necessity into a set of API servers encapsulated by a Cactus node. Cactus nodes can integrate innovative core plugins that combine them in different ways. Finally 3), business logic plugins that implement the core logic of a business utilizing infrastructure that Cactus provides access. - -In more technical terms, a `ConfigService`object is initialized for each Cactus node (describing, for example, the private keys for that Cactus node, public keys of the members of the consortium, protocols supported). Then, multiple plugins that expose a REST API can be installed on the node. Those plugins are accessible to the node via the plugin registry: an abstraction that allows one to easily manage and configure installed plugins, including business logic plugins. - -Client applications can then be built to operate the Cactus nodes, manage deployments, and call business logic plugins. - -# 3. Example Use Cases - -Specific use cases that we intend to support. -The core idea is to support as many use-cases as possible by enabling interoperability -between a large variety of ledgers specific to certain mainstream or exotic use cases. - - -The following table summarizes the use cases that will be explained in more detail in the following sections. FA, NFA, and D denote a fungible asset, a non-fungible asset, and data, respectively. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Object type of Blockchain A Object type of Blockchain BLedger transferAtomic swapLedger interactionLedger entry point coordination
One-wayTwo-wayOne-wayTwo-way
D D3.8
3.11		3.8
3.9		---3.10
FAFA3.43.73.63.63.6
NFANFA-----
FAD--3.5--
DFA--
NFAD-----
DNFA--
FANFA-----
NFAFA--
- -## 3.1 Asset Trade - -| Use Case Attribute Name | Use Case Attribute Value | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Use Case Title | Asset Trade | -| Use Case | TBD | -| Interworking patterns | TBD | -| Type of Social Interaction | TBD | -| Narrative | TBD | -| Actors | TBD | -| Goals of Actors | TBD | -| Success Scenario | TBD | -| Success Criteria | TBD | -| Failure Criteria | TBD | -| Prerequisites | TBD | -| Comments | | - -## 3.2 Electricity Trade - -| Use Case Attribute Name | Use Case Attribute Value | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Use Case Title | Electricity Trade | -| Use Case | TBD | -| Interworking patterns | TBD | -| Type of Social Interaction | TBD | -| Narrative | TBD | -| Actors | TBD | -| Goals of Actors | TBD | -| Success Scenario | TBD | -| Success Criteria | TBD | -| Failure Criteria | TBD | -| Prerequisites | TBD | -| Comments | | - -## 3.3 Supply chain - -| Use Case Attribute Name | Use Case Attribute Value | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Use Case Title | Supply Chain | -| Use Case | TBD | -| Interworking patterns | TBD | -| Type of Social Interaction | TBD | -| Narrative | TBD | -| Actors | TBD | -| Goals of Actors | TBD | -| Success Scenario | TBD | -| Success Criteria | TBD | -| Failure Criteria | TBD | -| Prerequisites | TBD | -| Comments | | - -## 3.4 Ethereum to Quorum Asset Transfer - -| Use Case Attribute Name | Use Case Attribute Value | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Use Case Title | Ethereum to Quorum Escrowed Asset Transfer | -| Use Case | 1. `User A` owns some assets on an Ethereum ledger
2. `User A` asks `Exchanger` to exchange specified amount of assets on Ethereum ledger, and receives exchanged asset at the Quorum ledger. -| Interworking patterns | Value transfer | -| Type of Social Interaction | Escrowed Asset Transfer | -| Narrative | A person (`User A`) has multiple accounts on different ledgers (Ethereum, Quorum) and he wishes to send some assets from Ethereum ledger to a Quorum ledger with considering conversion rate. The sent asset on Ethereum will be received by Exchanger only when he successfully received converted asset on Quorum ledger. | -| Actors | 1. `User A`: The person or entity who has ownership of the assets associated with its accounts on ledger. | -| Goals of Actors | `User A` loses ownership of sent assets on Ethereum, but he will get ownership of exchanged asset value on Quorum. | -| Success Scenario | Transfer succeeds without issues. Asset is available on both Ethereum and Quorum ledgers. | -| Success Criteria | Transfer asset on Quorum was succeeded. | -| Failure Criteria | Transfer asset on Quorum was failed. | -| Prerequisites | 1. Ledgers are provisioned
2. `User A` and `Exchanger` identities established on both ledgers
3. `Exchanger` authorized business logic plugin to operate the account on Quorum ledger.
4.`User A` has access to Hyperledger Cactus deployment | -| Comments | | - -
- - -
- -## 3.5 Escrowed Sale of Data for Coins - - -| W3C Use Case Attribute Name | W3C Use Case Attribute Value | -|-----------------------------|------------------------------------------------| -| Use Case Title | Escrowed Sale of Data for Coins | -| Use Case | 1. `User A` initiates (proposes) an escrowed transaction with `User B`
2. `User A` places funds, `User B` places the data to a digital escrow service.
3. They both observe each other's input to the escrow service and decide to proceed.
4. Escrow service releases the funds and the data to the parties in the exchange. | -| Type of Social Interaction | Peer to Peer Exchange | -| Narrative | Data in this context is any series of bits stored on a computer:
* Machine learning model
* ad-tech database
* digital/digitized art
* proprietary source code or binaries of software
* etc.

`User A` and B trade the data and the funds through a Hyperledger Cactus transaction in an atomic swap with escrow securing both parties from fraud or unintended failures.
Through the transaction protocol's handshake mechanism, A and B can agree (in advance) upon

* The delivery addresses (which ledger, which wallet)
* the provider of escrow that they both trust
* the price and currency

Establishing trust (e.g. Is that art original or is that machine learning model has the advertised accuracy) can be facilitated through the participating DLTs if they support it. Note that `User A` has no way of knowing the quality of the dataset, they entirely rely on `User B`'s description of its quality (there are solutions to this problem, but it's not within the scope of our use case to discuss these). | -| Actors | 1. `User A`: A person or business organization with the intent to purchase data.
2. `User B`: A person or business entity with data to sell. | -| Goals of Actors | `User A` wants to have access to data for an arbitrary reason such as having a business process that can enhanced by it.
`User B`: Is looking to generate income/profits from data they have obtained/created/etc. | -| Success Scenario | Both parties have signaled to proceed with escrow and the swap happened as specified in advance. | -| Success Criteria | `User A` has access to the data, `User B` has been provided with the funds. | -| Failure Criteria | Either party did not hold up their end of the exchange/trace. | -| Prerequisites | `User A` has the funds to make the purchase
`User B` has the data that `User A` wishes to purchase.
`User A` and B can agree on a suitable currency to denominate the deal in and there is also consensus on the provider of escrow. | -| Comments | Hyperledger Private Data: https://hyperledger-fabric.readthedocs.io/en/release-1.4/private_data_tutorial.html
Besu Privacy Groups: https://besu.hyperledger.org/en/stable/Concepts/Privacy/Privacy-Groups/ | - -
- -
- -## 3.6 Money Exchanges - -Enabling the trading of fiat and virtual currencies in any permutation of possible pairs. - -> On the technical level, this use case is the same as the one above and therefore the specific details were omitted. - -## 3.7 Stable Coin Pegged to Other Currency - - -| W3C Use Case Attribute Name | W3C Use Case Attribute Value | -|-----------------------------|------------------------------------------------| -| Use Case Title | Stable Coin Pegged to Other Currency | -| Use Case | 1. `User A` creates their own ledger
2. `User A` deploys Hyperledger Cactus in an environment set up by them.
3. `User A` implements necessary plugins for Hyperledger Cactus to interface with their ledger for transactions, token minting and burning.| -| Type of Social Interaction | Software Implementation Project | -| Narrative | Someone launches a highly scalable ledger with their own coin called ExampleCoin that can consistently sustain throughput levels of a million transactions per second reliably, but they struggle with adoption because nobody wants to buy into their coin fearing that it will lose its value. They choose to put in place a two-way peg with Bitcoin which guarantees to holders of their coin that it can always be redeemed for a fixed number of Bitcoins/USDs. | -| Actors | `User A`: Owner and/or operator of a ledger and currency that they wish to stabilize (peg) to other currencies | -| Goals of Actors | 1. Achieve credibility for their currency by backing funds.
2. Implement necessary software with minimal boilerplate code (most of which should be provided by Hyperledger Cactus) | -| Success Scenario | `User A` stood up a Hyperledger Cactus deployment with their self-authored plugins and it is possible for end user application development to start by leveraging the Hyperledger Cactus REST APIs which now expose the functionalities provided by the plugin authored by ``User A`` | -| Success Criteria | Success scenario was achieved without significant extra development effort apart from creating the Hyperledger Cactus plugins. | -| Failure Criteria | Implementation complexity was high enough that it would've been easier to write something from scratch without the framework | -| Prerequisites | * Operational ledger and currency
*Technical knowledge for plugin implementation (software engineering) | -| Comments | | - -> Sequence diagram omitted as use case does not pertain to end users of Hyperledger Cactus itself. - -### 3.7.1 With Permissionless Ledgers (BTC) - -A BTC holder can exchange their BTC for ExampleCoins by sending their BTC to `ExampleCoin Reserve Wallet` and the equivalent amount of coins get minted for them -onto their ExampleCoin wallet on the other network. - -An ExampleCoin holder can redeem their funds to BTC by receiving a Proof of Burn on the ExampleCoin ledger and getting sent the matching amount of BTC from the `ExampleCoin Reserve Wallet` to their BTC wallet. - - - -### 3.7.2 With Fiat Money (USD) - -Very similar idea as with pegging against BTC, but the BTC wallet used for reserves -gets replaced by a traditional bank account holding USD. - -
- -## 3.8 Healthcare Data Sharing with Access Control Lists - -| W3C Use Case Attribute Name | W3C Use Case Attribute Value | -|-----------------------------|------------------------------------------------| -| Use Case Title | Healthcare Data Sharing with Access Control Lists | -| Use Case | 1. `User A` (patient) engages in business with `User B` (healthcare provider)
2. `User B` requests permission to have read access to digitally stored medical history of `User A` and write access to log new entries in said medical history.
3.`User A` receives a prompt to grant access and allows it.
4. `User B` is granted permission through ledger specific access control/privacy features to the data of `User A`. | -| Type of Social Interaction | Peer to Peer Data Sharing | -| Narrative | Let's say that two healthcare providers have both implemented their own blockchain based patient data management systems and are looking to integrate with each other to provide patients with a seamless experience when being directed from one to another for certain treatments. The user is in control over their data on both platforms separately and with a Hyperledger Cactus backed integration they could also define fine grained access control lists consenting to the two healthcare providers to access each other's data that they collected about the patient. | -| Actors | * `User A`: Patient engaging in business with a healthcare provider
* `User B`: Healthcare provider offering services to `User A`. Some of said services depend on having access to prior medical history of `User A`. | -| Goals of Actors | * `User A`: Wants to have fine grained access control in place when it comes to sharing their data to ensure that it does not end up in the hands of hackers or on a grey data market place.
`User B` | -| Success Scenario | `User B` (healthcare provider) has access to exactly as much information as they need to and nothing more. | -| Success Criteria | There's cryptographic proof for the integrity of the data. Data hasn't been compromised during the sharing process, e.g. other actors did not gain unauthorized access to the data by accident or through malicious actions. | -| Failure Criteria | `User B` (healthcare provider) either does not have access to the required data or they have access to data that they are not supposed to. | -| Prerequisites | `User A` and `User B` are registered on a ledger or two separate ledgers that support the concept of individual data ownership, access controls and sharing. | -| Comments | It makes most sense for best privacy if `User A` and `User B` are both present with an identity on the same permissioned, privacy-enabled ledger rather than on two separate ones. This gives `User A` an additional layer of security since they can know that their data is still only stored on one ledger instead of two (albeit both being privacy-enabled)| - - -
- -## 3.9 Integrate Existing Food Traceability Solutions - -| W3C Use Case Attribute Name | W3C Use Case Attribute Value | -|-----------------------------|------------------------------| -| Use Case Title | Food Traceability Integration | -| Use Case | 1. `Consumer` is evaluating a food item in a physical retail store.
2. `Consumer` queries the designated end user application designed to provide food traces. 3. `Consumer` makes purchasing decision based on food trace.| -| Type of Social Interaction | Software Implementation Project | -| Narrative | Both `Organization A` and `Organization B` have separate products/services for solving the problem of verifying the source of food products sold by retailers.
A retailer has purchased the food traceability solution from `Organization A` while a food manufacturer (whom the retailer is a customer of) has purchased their food traceability solution from `Organization B`.
The retailer wants to provide end to end food traceability to their customers, but this is not possible since the chain of traceability breaks down at the manufacturer who uses a different service or solution. `Cactus` is used as an architectural component to build an integration for the retailer which ensures that consumers have access to food tracing data regardless of the originating system for it being the product/service of `Organization A` or `Organization B`. | -| Actors | `Organization A`, `Organization B` entities whose business has to do with food somewhere along the global chain from growing/manufacturing to the consumer retail shelves.
`Consumer`: Private citizen who makes food purchases in a consumer retail goods store and wishes to trace the food end to end before purchasing decisions are finalized. | -| Goals of Actors | `Organization A`, `Organization B`: Provide `Consumer` with a way to trace food items back to the source.
`Consumer`: Consume food that's been ethically sourced, treated and transported. | -| Success Scenario | `Consumer` satisfaction increases on account of the ability to verify food origins. | -| Success Criteria | `Consumer` is able to verify food items' origins before making a purchasing decision. | -| Failure Criteria | `Consumer` is unable to verify food items' origins partially or completely. | -| Prerequisites | 1. `Organization A` and `Organization B` are both signed up for blockchain enabled software services that provide end to end food traceability solutions on their own but require all participants in the chain to use a single solution in order to work.
2. Both solutions of `Organization A` and `B` have terms and conditions such that it is possible technically and legally to integrate the software with each other and `Cactus`. | -| Comments | | - - - ---- - - - -
- -## 3.10 End User Wallet Authentication/Authorization - -| W3C Use Case Attribute Name | W3C Use Case Attribute Value | -|-----------------------------|------------------------------| -| Use Case Title | Wallet Authentication/Authorization | -| Use Case | 1. `User A` has separate identities on different permissioned and permissionless ledgers in the form of private/public key pairs (Public Key Infrastructure).
2. `User A` wishes to access/manage these identities through a single API or user interface and opts to on-board the identities to a `Cactus` deployment.
3. `User A` performs the on-boarding of identities and is now able to interact with wallets attached to said identities through `Cactus` or end user applications that leverage `Cactus` under the hood (e.g. either by directly issuing API requests or using an application that does so.| -| Type of Social Interaction | Identity Management | -| Narrative | End user facing applications can provide a seamless experience connecting multiple permissioned (or permissionless) networks for an end user who has a set of different identity proofs for wallets on different ledgers. | -| Actors | `User A`: The person or entity whose identities get consolidated within a single `Cactus` deployment | -| Goals of Actors | `User A`: Convenient way to manage an array of distinct identities with the trade-off that a `Cactus` deployment must be trusted with the private keys of the identities involved (an educated decision on the user's part). | -| Success Scenario | `User A` is able to interact with their wallets without having to access each private key individually. | -| Success Criteria | `User A`'s credentials are safely stored in the `Cactus` keychain component where it is the least likely that they will be compromised (note that it is never impossible, but least unlikely, definitely) | -| Failure Criteria | `User A` is unable to import identities to `Cactus` for a number of different reasons such as key format incompatibilities. | -| Prerequisites | 1. `User A` has to have the identities on the various ledgers set up prior to importing them and must have access to the private | -| Comments | | - - - ---- - - - -
- -## 3.11 Blockchain Migration - - -| Use Case Attribute Name | Use Case Attribute Value | -| -------------------------- | -------------------------------------------- | -| Use Case Title | Blockchain Migration | -| Use Case | 1. `Consortium A` operates a set of services on the source blockchain.
2. `Consortium A` decides to use another blockchain instance to run its services.
3. `Consortium A` migrates the existing assets and data to the target blockchain.
4. `Consortium A` runs the services on the target blockchain. -| Interworking patterns | Value transfer, Data transfer | -| Type of Social Interaction | Asset and Data Transfer | -| Narrative | A group of members (`Consortium A`) that operates the source blockchain (e.g., Hyperledger Fabric instance) would like to migrate the assets, data, and functionality to the target blockchain (e.g., Hyperledger Besu instance) to expand their reach or to benefits from better performance, lower cost, or enhanced privacy offered by the target blockchain. In the context of public blockchains, both the group size and the number of services could even be one. For example, a user that runs a Decentralized Application (DApp) on a publication blockchain wants to migrate DApp's assets, data, and functionality to a target blockchain that is either public or private.
The migration is initiated only after all members of `Consortium A` provide their consent to migrate. During the migration, assets and data that are required to continue the services are copied to the target blockchain. A trusted intermediatory (e.g., Oracle) is also authorized by the members of `Consortium A` to show the current state of assets and data on source blockchain to the target blockchain.
Assets on the source blockchain are burned and smart contracts are destructed during the migration to prevent double-spending. Proof-of-burn is verified on the target blockchain before creating the assets, smart contracts, or their state using the following process:
1. `Consortium A` requests smart-contract on the target blockchain (via `Cactus`) to transfer their asset/data, which will then wait until confirmation from the smart contract on the source blockchain.
2. `Consortium A` requests smart contract on source blockchain (via `Cactus`) to burn their asset/data.
3. Smart contract on source blockchain burns the asset/data and notifies that to the smart contract on the target blockchain.
4. Given the confirmation from Step 3, the smart contract on target blockchain creates asset/data.
After the migration, future transactions are processed on the target blockchain. In contrast, requests to access historical transactions are directed to the source blockchain. As assets are burned and smart contracts are destructed, any future attempt to manipulate them on the source blockchain will fail.
Regardless of whether the migration involves an entire blockchain or assets, data, and smart contracts of a DApp, migration requires lots of technical effort and time. The `Blockchain Migration` feature from `Cactus` can provide support for doing so by connecting source and target blockchains; proving values and proof-of-burn of assets, smart contracts, and data imported from the source blockchain to the target; and then performing the migration task. | -| Actors | 1. `Consortium A`: The group of entities operating on the source blockchain who collectively aims at performing the migration to the target blockchain. | -| Goals of Actors | 1. `Consortium A`: Wants to be able to operate its services on the target blockchain while gaining its benefits such as better performance, lower cost, or enhanced privacy. | -| Success Scenario | Asset and data (including smart contracts) are available on the target blockchain, enabling `Consortium A`'s services to operate on the target blockchain.| -| Success Criteria | Migration starts at a set time, and all desired assets and data, as well as their histroy have been migrated in a decentralized way. | -| Failure Criteria | States of all assets and data on the target blockchain do not match the states on the source blockchain before migration, e.g., when transactions replayed on target blockchain are reordered.
`Consortium A` is unable to migrate to the target blockchain for several reasons, such as -inability to recreate the same smart contract logic, inability to arbitrary recreate native assets on target blockchain, and lack of access to private keys of external accounts. | -| Prerequisites | 1. `Consortium A` wants to migrate the assets and data on the source blockchain, and have chosen a desirable target blockchain.
2. Migration plan and window are informed to all members of the consortium, and they agree to the migration.
3. `Consortium A` has write and execute permissions on the target blockchain. | -| Comments | * `Consortium A` is the governance body of services running on the source blockchain.
* Data include smart contracts and their data originating from the source blockchain. Depending on the use case, a subset of the assets and data may be recreated on the target blockchain.
* This use case relates to the use cases implying asset and data portability (e.g., 2.1). However, migration is mostly one-way and nonreversible.
* This use case provides blockchain portability; thus, retains blockchain properties across migration, reduces costs, time to migration, and foster blockchain adoption. | - --- -**Motivation** - -The suitability of a blockchain platform regarding a use case depends on the underlying blockchain properties. -As blockchain technologies are maturing at a fast pace, in particular private blockchains, its properties such as performance (i.e., throughput, latency, or finality), transaction fees, and privacy might change. -Also, blockchain platform changes, bug fixes, security, and governance issues may render an existing application/service suboptimal. -Further, business objectives such as the interest to launch own blockchain instance, partnerships, mergers, and acquisitions may motivate a migration. -Consequently, this creates an imbalance between the user expectations and the applicability of the existing solution. -It is, therefore, desirable for an organization/consortium to be able to replace the blockchain providing the infrastructure to a particular application/service. - -Currently, when a consortium wants to migrate the entire blockchain or user wants to migrate a DApp on a public blockchain (e.g., the source blockchain became obsolete, cryptographic algorithms are no longer secure, and business reasons), the solution is to re-implement business logic using a different blockchain platform, and arbitrary recreate the assets and data on the target blockchain, yielding great effort and time, as well as losing blockchain properties such as immutability, consistency, and transparency. -Data migrations have been performed before on public blockchains [[2](#8-references), [3](#8-references), [4](#8-references)] to render flexibility to blockchain-based solutions. -Such work proposes data migration capabilities and patterns for public, permissionless blockchains, in which a user can specify requirements and scope for the blockchain infrastructure supporting their service. - -### 3.11.1 Blockchain Data Migration -Data migration corresponds to capturing the subset of assets and data on a source blockchain and constructing a representation of those in a target blockchain. Note that the models underlying both blockchains do not need to be the same (e.g., world state model in Hyperledger Fabric vs account-balance model in Ethereum). -For migration to be effective, it should be possible to capture the necessary assets and data from the source blockchain and to write them on the target blockchain. - - - - -### 3.11.2 Blockchain Smart Contract Migration -The task of migrating a smart contract comprises the task of migrating the smart contract logic and data embedded in it. In specific, the data should be accessible and writeable on another blockchain. When the target blockchain can execute a smart contract written for the source blockchain, execution behavior can be preserved by redeploying the same smart contract (e.g., reusing a smart contract written for Ethereum on Hyperledger Besu) and recreating its assets and data. If code reuse is not possible (either at source or binary code level), the target blockchain's virtual machine should support the computational complexity of the source blockchain (e.g., one cannot migrate all Ethereum smart contracts to Bitcoin, but the other way around is feasible). -Automatic smart contract migration (with or without translation) yields risks for enterprise blockchain systems, and thus the solution is nontrivial [[4](#8-references)]. - -### 3.11.3 Semi-Automatic Blockchain Migration - -By expressing a user's preferences in terms of functional and non-functional requirements, `Cactus` can recommend a set of suitable blockchains, as the target for the migration. -Firstly, a user could know in real-time the characteristics of the target blockchain that would influence the migration decision. For instance, the platform can analyze the cost of writing data to Ethereum, Ether:USD exchange rate, average inter-block time, transaction throughput, and network hash rate [[3](#8-references)]. -Based on those characteristics and user-defined requirements, `Cactus` proposes a migration with indicators such as predicted cost, time to complete the migration, and the likelihood of success. -For example, when transaction inclusion time or fee on Ethereum exceeds a threshold, `Cactus` may choose Polkadot platform, as it yields lower transaction inclusion time or fee. `Cactus` then safely migrate assets, data, and future transactions from Ethereum to Polkadot, without compromising the solution in production. - This feature is more useful for public blockchains. - - -
- - -# 4. Software Design - -## 4.1. Principles - -### 4.1.1. Wide support - -Interconnect as many ecosystems as possible regardless of technology limitations - -### 4.1.2. Plugin Architecture from all possible aspects - -Identities, DLTs, service discovery. Minimize how opinionated we are to really embrace interoperability rather than silos and lock-in. Closely monitor community feedback/PRs to determine points of contention where core Hyperledger Cactus code could be lifted into plugins. Limit friction to adding future use cases and protocols. - -### 4.1.3. Prevent Double spending Where Possible - -Two representations of the same asset do not exist across the ecosystems at the same time unless clearly labelled as such [As of Oct 30 limited to specific combinations of DLTs; e.g. not yet possible with Fabric + Bitcoin] - -### 4.1.4 DLT Feature Inclusivity - -Each DLT has certain unique features that are partially or completely missing from other DLTs. -Hyperledger Cactus - where possible - should be designed in a way so that these unique features are accessible even when interacting with a DLT through Hyperledger Cactus. A good example of this principle in practice would be Kubernetes CRDs and operators that allow the community to extend the Kubernetes core APIs in a reusable way. - -### 4.1.5 Low impact - -Interoperability does not redefine ecosystems but adapts to them. Governance, trust model and workflows are preserved in each ecosystem -Trust model and consensus must be a mandatory part of the protocol handshake so that any possible incompatibilities are revealed up front and in a transparent way and both parties can “walk away” without unintended loss of assets/data. -The idea comes from how the traditional online payment processing APIs allow merchants to specify the acceptable level of guarantees before the transaction can be finalized (e.g. need pin, signed receipt, etc.). -Following the same logic, we shall allow transacting parties to specify what sort of consensus, transaction finality, they require. -Consensus requirements must support predicates, e.g. “I am on Fabric, but will accept Bitcoin so long X number of blocks were confirmed post-transaction” -Requiring KYC (Know Your Customer) compliance could also be added to help foster adoption as much as possible. - -### 4.1.6 Transparency - -Cross-ecosystem transfer participants are made aware of the local and global implications of the transfer. Rejection and errors are communicated in a timely fashion to all participants. -Such transparency should be visible as trustworthy evidence. - -### 4.1.7 Automated workflows - -Logic exists in each ecosystem to enable complex interoperability use-cases. Cross-ecosystem transfers can be automatically triggered in response to a previous one. -Automated procedure, which is regarding error recovery and exception handling, should be executed without any interruption. - -### 4.1.8 Default to Highest Security - -Support less secure options, but strictly as opt-in, never opt-out. - -### 4.1.9 Transaction Protocol Negotiation - -Participants in the transaction must have a handshake mechanism where they agree on one of the supported protocols to use to execute the transaction. The algorithm looks an intersection in the list of supported algorithms by the participants. - -### 4.1.10 Avoid modifying the total amount of digital assets on any blockchain whenever possible - -We believe that increasing or decreasing the total amount of digital assets might weaken the security of blockchain, since adding or deleting assets will be complicated. Instead, intermediate entities (e.g. exchanger) can pool and/or send the transfer. - -### 4.1.11 Provide abstraction for common operations - -Our communal modularity should extend to common mechanisms to operate and/or observe transactions on blockchains. - -### 4.1.12 Integration with Identity Frameworks (Moonshot) - -Do not expend opinions on identity frameworks just allow users of `Cactus` to leverage the most common ones and allow for future expansion of the list of supported identity frameworks through the plugin architecture. -Allow consumers of `Cactus` to perform authentication, authorization and reading/writing of credentials. - -Identity Frameworks to support/consider initially: - -* [Hyperledger Indy (Sovrin)](https://www.hyperledger.org/projects/hyperledger-indy) -* [DIF](https://identity.foundation/) -* [DID](https://www.w3.org/TR/did-core/) - -## 4.2 Feature Requirements - -### 4.2.1 New Protocol Integration - -Adding new protocols must be possible as part of the plugin architecture allowing the community to propose, develop, test and release their own implementations at will. - -### 4.2.2 Proxy/Firewall/NAT Compatibility - -Means for establishing bidirectional communication channels through proxies/firewalls/NAT wherever possible - -### 4.2.3 Bi-directional Communications Layer - -Using a blockchain agnostic bidirectional communication channel for controlling and monitoring transactions on blockchains through proxies/firewalls/NAT wherever possible. - * Blockchains vary on their P2P communication protocols. It is better to build a modular method for sending/receiving generic transactions between trustworthy entities on blockchains. - -### 4.2.4 Consortium Management - -Consortiums can be formed by cooperating entities (person, organization, etc.) who wish to contribute hardware/network -resources to the operation of a `Cactus` cluster. - -What holds the consortiums together is the consensus among the members on who the members are, which is defined by the -nodes' network hosts and public keys. The keys are produced from the Secp256k1 curve. - -The consortium plugin(s) main responsibility is to provide information about the consortium's members, nodes and public keys. -`Cactus` does not prescribe any specific consensus algorithm for the addition or removal of consortium members, but -rather focuses on the technical side of making it possible to operate a cluster of nodes under the ownership of -separate entities without downtime while also keeping it possible to add/remove members. -It is up to authors of plugins who can implement any kind of consortium management functionality as they see fit. -The default implementation that Cactus ships with is in the `cactus-plugin-consortium-manual` package which - as the -name implies - leaves the achievement of consensus to the initial set of members who are expected to produce the initial -set of network hosts/public keys and then configure their Cactus nodes accordingly. -This process and the details of operation are laid out in much more detail in the dedicated section of the manual -consortium management plugin further below in this document. - -After the forming of the consortium with it's initial set of members (one or more) it is possible to enroll or remove certain new or existing members, but this can vary based on different implementations. - -## 4.3 Working Policies - -1. Participants can insist on a specific protocol by pretending that they only support said protocol only. -2. Protocols can be versioned as the specifications mature -3. The two initially supported protocols shall be the ones that can satisfy the requirements for Fujitsu's and Accenture's implementations respectively - -
- -# 5. Architecture - -## 5.1 Deployment Scenarios - -Hyperledger Cactus has several integration patterns as the following. - -- Note: In the following description, **Value (V)** means numerical assets (e.g. money). **Data (D)** means non-numerical assets (e.g. ownership proof). Ledger 1 is source ledger, Ledger 2 is destination ledger. - -| No. | Name | Pattern | Consistency | -| --- | ------------------- | ------- | ---------------------------------------------------------------------------------------------- | -| 1. | value transfer | V -> V | check if V1 = V2
(as V1 is value on ledger 1, V2 is value on ledger 2) | -| 2. | value-data transfer | V -> D | check if data transfer is successful when value is transferred | -| 3. | data-value transfer | D -> V | check if value transfer is successful when data is transferred | -| 4. | data transfer | D -> D | check if all D1 is copied on ledger 2
(as D1 is data on ledger 1, D2 is data on ledger 2) | -| 5. | data merge | D <-> D | check if D1 = D2 as a result
(as D1 is data on ledger 1, D2 is data on ledger 2) | - - -There's a set of building blocks (members, nodes, API server processes, plugin instances) that you can use when defining (founding) a consortium and these building blocks relate to each other in a way that can be expressed with an entity relationship diagram which can be seen below. -The composability rules can be deducted from how the diagram elements (entities) are connected (related) to each other, e.g. the API server process can have any number of plugin instances in it and a node can contain any number of API server processes, and so on until the top level construct is reached: the consortium. - -> Consortium management does not relate to achieving consensus on data/transactions involving individual ledgers, merely about consensus on the metadata of a consortium. - - - -Now, with these composability rules in mind, let us demonstrate a few different deployment scenarios (both expected and exotic ones) to showcase the framework's flexibility in this regard. - -### 5.1.1 Production Deployment Example - -Many different configurations are possible here as well. -One way to have two members form a consortium and both of those members provide highly available, high throughput services is to have a deployment as shown on the below figure. -What is important to note here is that this consortium has 2 nodes, 1 for each member -and it is irrelevant how many API servers those nodes have internally because they -all respond to requests through the network host/web domain that is tied to the -node. -One could say that API servers do not have a distinguishable identity relative to -their peer API servers, only the higher-level nodes do. - - - -### 5.1.2 Low Resource Deployment Example - -This is an example to showcase how you can pull up a full consortium even from -within a single operating system process (API server) with multiple members and -their respective nodes. It is not something that's recommended for a production -grade environment, ever, but it is great for demos and integration tests where -you have to simulate a fully functioning consortium with as little hardware footprint -as possible to save on time and cost. - -The individual nodes/API servers are isolated by listening on separate TCP ports -of the machine they are hosted on: - - - - -## 5.2 System architecture and basic flow - -Hyperledger Cactus will provide integrated service(s) by executing ledger operations across multiple blockchain ledgers. The execution of operations are controlled by the module of Hyperledger Cactus which will be provided by vendors as the single Hyperledger Cactus Business Logic plugin. -The supported blockchain platforms by Hyperledger Cactus can be added by implementing new Hyperledger Cactus Ledger plugin. -Once an API call to Hyperledger Cactus framework is requested by a User, Business Logic plugin determines which ledger operations should be executed, and it ensures reliability on the issued integrated service is completed as expected. -Following diagram shows the architecture of Hyperledger Cactus based on the discussion made at Hyperledger Cactus project calls. -The overall architecture is as the following figure. - - - -### 5.2.1 Definition of key components in system architecture - -Key components are defined as follows: -- **Business Logic Plugin**: The entity executes business logic and provide integration services that are connected with multiple blockchains. The entity is composed by web application or smart contract on a blockchain. The entity is a single plugin and required for executing Hyperledger Cactus applications. -- **CACTUS Node Server**: The server accepts a request from an End-user Application, and return a response depending on the status of the targeted trade. Trade ID will be assigned when a new trade is accepted. -- **End-user Application**: The entity submits API calls to request a trade, which invokes a set of transactions on Ledger by the Business Logic Plugin. -- **Ledger Event Listener**: The standard interface to handle various kinds of events(LedgerEvent) regarding asynchronous Ledger operations. The LedgerEvent will be notified to appropriate business logic to handle it. -- **Ledger Plugin**: The entity communicates Business Logic Plugin with each ledger. The entity is composed by a validator and a verifier as follows. The entity(s) is(are) chosen from multiple plugins on configuration. -- **Service Provider Application**: The entity submits API calls to control the cmd-api-server when it is enabling/disabling Ledger plugins, or shutting down the server. Additional commands may be available on Admin API since **Server controller** is implementation-dependent. -- **Validator**: The entity monitors transaction records of Ledger operation, and it determines the result(success, failed, timeouted) from the transaction records. -Validator ensure the determined result with attaching digital signature with "Validator key" which can be verified by "Verifier". -- **Validator Server**: The server accepts a connection from Verifier, and it provides Validator API, which can be used for issuing signed transactions and monitoring Ledger behind it. The LedgerConnector will be implemented for interacting with the Ledger nodes. -- **Verifier**: The entity accepts only successfully verified operation results by verifying the digital signature of the validator. Verifier will be instantiated by calling the VerifierFactory#create method with associated with the Validator to connect. Each Verifier may be temporarily enabled or disabled. Note that "Validator" is apart from "Verifier" over a bi-directional channel. -- **Verifier Registry**: The information about active Verifier. The VerifierFactory uses this information to instantiate Verifier for the Business Logic Plugin. - -### 5.2.2 Bootstrapping Cactus application - -Key components defined in 4.2.1 becomes ready to serve Cactus application service after following procedures: -1. Start `Validator`: The `Validator` of `Ledger Plugin` which is chosen for each `Ledger` depending the platform technology used (ex. Fabric, Besu, etc.) will be started by the administrator of `Validator`. `Validator` becomes ready status to accept connection from `Verifier` after initialization process is done. -2. Start `Business Logic Plugin` implementation: The administrator of Cactus application service starts `Business Logic Plugin` which is implemented to execute business logic(s). `Business Logic Plugin` implementation first checks availability of depended `Ledger Plugin(s)`, then it tries to enable each `Ledger Plugin` with customized profile for actual integrating `Ledger`. This availability checks also covers determination on the status of connectivity from `Verifier` to `Validator`. The availability of each `Ledger` is registered and maintained at `Cactus Routing Interface`, and it allows bi-directional message communication between `Business Logic Plugin` and `Ledger`. - -### 5.2.3 Processing Service API call - - `Service API call` is processed as follows: -- **Step 1**: "Application user(s)" submits an API call to "Cactus routing interface". -- **Step 2**: The API call is internally routed to "Business Logic Plugin" by "Cactus Routing Interface" for initiating associated business logic. -Then, "Business Logic Plugin" determines required ledger operation(s) to complete or abort a business logic. -- **Step 3**" "Business Logic Plugin" submits API calls to request operations on "Ledger(s)" wrapped with "Ledger Plugin(s)". Each API call will be routed to designated "Ledger Plugin" by "Routing Interface". -- **Step 4**: "Ledger Plugin" sends an event notification to "Business Logic Plugin" via "Cactus Routing Interface", when its sub-component "Verifier" detect an event regarding requested ledger operation to "Ledger". -- **Step 5**: "Business Logic Plugin" receives a message from "Ledger Plugin" and determines completion or continuous of the business logic. When the business logic requires to continuous operations go to "Step 3" ,or end the process. - -
- -## 5.3 APIs and communication protocols between Cactus components - -API for Service Application, communication protocol for business logic plugin to interact with "Ledger Plugins" will be described in this section. - -### 5.3.1 Cactus Service API - -Cactus Service API is exposed to Application user(s). This API is used to request for initializing a business logic which is implemented at **Business Logic Plugin**. It is also used for making inquery of execution status and final result if the business logic is completed. - -Following RESTful API design manner, the request can be mapped to one of CRUD operation with associated resource 'trade'. - -The identity of User Application is authenticated and is applied for access control rule(s) check which is implemented as part of **Business Logic Plugin**. - -NOTE: we are still open to consider other choose on API design patterns, such as gRPC or GraphQL. - -#### Open Endpoints - -Open endpoints require no authentication - -* [Login](login.md) : `POST /api/v1/bl/login` - -#### Restricted Endpoints - -Restricted endpoints require a valid Token to be included in the headder of the request. A Token can be acquired by calling [Login](). - -* [Request Execution of Trade(instance of business logic)]() : `POST /api/v1/bl/trades/` -* [Show Current Status of Trade]() : `GET /api/v1/bl/trades/(id)` -* [Show Business Logics]() : `GET /api/v1/bl/logics/` -* [Show Specification of Business Logic]() : `GET /api/v1/bl/logics/(id)` -* [Register a Wallet]() : `POST /api/v1/bl/wallets/` -* [Show Wallet List]() : `GET /api/v1/bl/wallets/` -* [Update Existing Wallets]() : `PUT /api/v1/bl/wallets/(id)` -* [Delete a Wallet]() : `DELETE /api/v1/bl/walllets/(id)` - -NOTE: resource `trade` and `logic` are cannot be updated nor delete - -### 5.3.2 Ledger plugin API - -Ledger plugin API is designed for allowing **Business Logic Plugin** to operate and/or monitor Ledger behind the components of **Verifier** and **Validator**. - -**Validator** provides a common set of functions that abstract communication between **Verifier** and **Ledger**. Please note that Validator will not have any privilege to manipulate assets on the Ledger behind it. -**Verifier** can receive requests from **Business Logic Plugin** and reply responses and events asynchronously. - -APIs of Verifier and Validator are described as the following table: - -| No. | Component | API Name | Input | Description | -| --- | --- | --- | --- | --- | -| 1. | Verifier | sendAsyncRequest | `contract` (object)
`method` (object)
`args` (object) | Sends an asynchronous request to the validator | -| 2. | Verifier | sendSyncRequest | `contract` (object)
`method` (object)
`args` (object) | Sends a synchronous request to the validator | -| 3. | Verifier | startMonitor | `id` (string)
`eventListener` (VerifierEventListener) | Request a verifier to start monitoring ledger | -| 4. | Verifier | stopMonitor | `id` (string) | Request a verifier to stop monitoring ledger | -| 5. | Validator | sendAsyncRequest | `args` (Object) | Called when the validator receives an asynchronous operation request from the verifier | -| 6. | Validator | sendSyncRequest | `args` (Object) | Called when the validator receives a synchronous operation request from the verifier | -| 7. | Validator | startMonitor | `cb` (function) | Called when monitoring ledger is needed | -| 8. | Validator | stopMonitor | none | Called when monitoring ledger is no longer needed | - -The detail information is described as following: - -- `packages/cactus-cmd-socketio-server/src/main/typescript/verifier/LedgerPlugin.ts` - - interface `IVerifier` - - ```typescript - interface IVerifier { - // BLP -> Verifier - sendAsyncRequest(contract: Object, method: Object, args: Object): Promise; - sendSyncRequest(contract: Object, method: Object, args: Object): Promise; - startMonitor(id: string, options: Object, eventListener: VerifierEventListener): Promise; - stopMonitor(id: string): void; - } - ``` - - - function `sendAsyncRequest(contract: object, method: object, args: object): Promise` - - description: - - Send a request to the validator (and the ledger behind it) that takes time to finish e.g. writing to the ledger. - - input parameters: - - `contract` (Object): specify the smart contract - - `method` (Object): name of the method - - `args` (Object): arguments to the method - - returns: - - `Promise`: `resolve()` when it successfully sent the request to the validator, `reject()` otherwise. - - - function `sendSyncRequest: Promise` - - description: - - Send a request to the validator, e.g. searching a datablock. - - input parameters: - - `contract` (Object): specify the smart contract - - `method` (Object): name of the method - - `args` (Object): arguments to the method - - returns: - - `Promise`: search result is returned. - - - function `startMonitor(id: string, options: Object, eventListener: VerifierEventListener): Promise` - - description: - - Request the verifier to start monitoring ledger. - - input parameters: - - `id` (string): a user (Business Logic Plugin) generated string to identify the ledgerEvent object. - - `options` (Object): parameters to monitor functionality in the validator. specify `{}` if no options are necessary - - `eventListener` (VerifierEventListener): the callback function of this object is called when there are new blocks written to the ledger. - - returns: - - `Promise`: `resolve()` when it successfully started monitoring, `reject()` otherwise. - - - function `stopMonitor(id: string): void` - - description: - - Request the verifier to remove an `eventListener` from event monitors list. - - input parameter: - - `id` (string): a string identifying the ledgerEvent. - - returns: - - none - - - interface `IValidator` - - ```typescript - interface IValidator { - // Verifier -> Validator - sendAsyncRequest(args: Object): Object; - sendSyncRequest(args: Object): Object; - startMonitor(cb: function): Promise; - stopMonitor(): void; - } - ``` - - - function `sendAsyncRequest(args: Object): Object` - - description: - - Send a request to the ledger that takes time to finish e.g. writing to the ledger. - The implementer of a validator for new distributed ledger technology (DLT) is expected to extract parameters from `args` object and cal the API (of the target DLT). - - input parameter: - - `args` (Object): parameters of verifier's `sendAsyncRequest` API are included in this object. - - returns: - - Object - - Editor's Note: check return type - - - function `sendSyncRequest(args: Object): Object` - - description: - - Send a request to a validator, e.g. searching a datablock. - - input parameter: - - `args` (Object): parameters of verifier's `sendSyncRequest` API are included in this object. - - returns: - - Object: result of the requested operation. - - - function `startMonitor(cb: function): Promise` - - description: - - Start monitoring of the ledger. - The implementer of a validator for new distributed ledger technology (DLT) is expected to start monitoring ledger events of the target DLT. - If there are any new block written to the ledger, the monitoring code should call `cb(data)`. - The parameter to the `cb` is the new data from the ledger. - - input parameter: - - `cb` (function): callback function called when there are new data in the ledger. - - returns: - - Promise: `resolve()` when it successfully started monitoring the ledger, `reject()` otherwise. - - - function `stopMonitor(void): void`: - - description: - - Stop monitoring the ledger. - - input parameter: - - none - - returns: - - none - -### 5.3.3 Exection of "business logic" at "Business Logic Plugin" - -The developper of **Business Logic Plugin** can implement business logic(s) as codes to interact with **Ledger Plugin**. -The interaction between **Business Logic Plugin** and **Ledger Plugin** includes: -- Submit a transaction request on targeted **Ledger Plugin** -- Make a inquery to targeted **Ledger Plugin** (ex. account balance inquery) -- Receive an event message, which contains transaction/inquery result(s) or error from **Ledger Plugin** - -NOTE: The transaction request is prepared by **Business Logic Plugin** using transaction template with given parameters - -The communication protocol between Business Logic Plugin, Verifier, and Validator as following: - - - -## 5.4 Technical Architecture - -### 5.4.1 Monorepo Packages - -Hyperledger Cactus is divided into a set of npm packages that can be compiled separately or all at once. - -All packages have a prefix of `cactus-*` to avoid potential naming conflicts with npm modules published by other Hyperledger projects. For example if both Cactus and Aries were to publish a package named `common` under the shared `@hyperledger` npm scope then the resulting fully qualified package name would end up being (without the prefix) as `@hyperledger/common` but with prefixes the conflict can be resolved as `@hyperledger/cactus-common` and `@hyperledger/aries-common`. Aries is just as an example here, we do not know if they plan on releasing packages under such names, but it also does not matter for the demonstration of ours. - -Naming conventions for packages: -* cmd-* for packages that ship their own executable -* All other packages should be named preferably as a single English word suggesting the most important feature/responsibility of the package itself. - -#### 5.4.1.1 cmd-api-server - -A command line application for running the API server that provides a unified REST based HTTP API for calling code. -Contains the kernel of Hyperledger Cactus. -Code that is strongly opinionated lives here, the rest is pushed to other packages that implement plugins or define their interfaces. -Comes with Swagger API definitions, plugin loading built-in. - -> By design this is stateless and horizontally scalable. - -**The main responsibilities of this package are:** - -##### 5.4.1.1.1 Runtime Configuration Parsing and Validation - -The core package is responsible for parsing runtime configuration from the usual sources (shown in order of precedence): -* Explicit instructions via code (`config.setHttpPort(3000);`) -* Command line arguments (`--http-port=3000`) -* Operating system environment variables (`HTTP_PORT=3000`) -* Static configuration files (config.json: `{ "httpPort": 3000 }`) - -The Apache 2.0 licensed node-convict library to be leveraged for the mechanical parts of the configuration parsing and validation: https://github.com/mozilla/node-convict - -##### 5.4.1.1.2 Configuration Schema - API Server - -To obtain the latest configuration options you can check out the latest source code of Cactus and then run this from the root folder of the project on a machine that has at least NodeJS 10 or newer installed: - -```sh -$ date -Mon 18 May 2020 05:09:58 PM PDT - -$ npx ts-node -e "import {ConfigService} from './packages/cactus-cmd-api-server/src/main/typescript/config/config-service'; console.log(ConfigService.getHelpText());" - -Order of precedent for parameters in descdending order: CLI, Environment variables, Configuration file. -Passing "help" as the first argument prints this message and also dumps the effective configuration. - -Configuration Parameters -======================== - - plugins: - Description: A collection of plugins to load at runtime. - Default: - Env: PLUGINS - CLI: --plugins - configFile: - Description: The path to a config file that holds the configuration itself which will be parsed and validated. - Default: Mandatory parameter without a default value. - Env: CONFIG_FILE - CLI: --config-file - logLevel: - Description: The level at which loggers should be configured. Supported values include the following: error, warn, info, debug, trace - Default: warn - Env: LOG_LEVEL - CLI: --log-level - cockpitHost: - Description: The host to bind the Cockpit webserver to. Secure default is: 127.0.0.1. Use 0.0.0.0 to bind for any host. - Default: 127.0.0.1 - Env: COCKPIT_HOST - CLI: --cockpit-host - cockpitPort: - Description: The HTTP port to bind the Cockpit webserver to. - Default: 3000 - Env: COCKPIT_PORT - CLI: --cockpit-port - cockpitWwwRoot: - Description: The file-system path pointing to the static files of web application served as the cockpit by the API server. - Default: packages/cactus-cmd-api-server/node_modules/@hyperledger/cactus-cockpit/www/ - Env: COCKPIT_WWW_ROOT - CLI: --cockpit-www-root - apiHost: - Description: The host to bind the API to. Secure default is: 127.0.0.1. Use 0.0.0.0 to bind for any host. - Default: 127.0.0.1 - Env: API_HOST - CLI: --api-host - apiPort: - Description: The HTTP port to bind the API server endpoints to. - Default: 4000 - Env: API_PORT - CLI: --api-port - apiCorsDomainCsv: - Description: The Comma seperated list of domains to allow Cross Origin Resource Sharing from when serving API requests. The wildcard (*) character is supported to allow CORS for any and all domains, however using it is not recommended unless you are developing or demonstrating something with Cactus. - Default: Mandatory parameter without a default value. - Env: API_CORS_DOMAIN_CSV - CLI: --api-cors-domain-csv - publicKey: - Description: Public key of this Cactus node (the API server) - Default: Mandatory parameter without a default value. - Env: PUBLIC_KEY - CLI: --public-key - privateKey: - Description: Private key of this Cactus node (the API server) - Default: Mandatory parameter without a default value. - Env: PRIVATE_KEY - CLI: --private-key - keychainSuffixPrivateKey: - Description: The key under which to store/retrieve the private key from the keychain of this Cactus node (API server)The complete lookup key is constructed from the ${KEYCHAIN_SUFFIX_PRIVATE_KEY} template. - Default: CACTUS_NODE_PRIVATE_KEY - Env: KEYCHAIN_SUFFIX_PRIVATE_KEY - CLI: --keychain-suffix-private-key - keychainSuffixPublicKey: - Description: The key under which to store/retrieve the public key from the keychain of this Cactus node (API server)The complete lookup key is constructed from the ${KEYCHAIN_SUFFIX_PRIVATE_KEY} template. - Default: CACTUS_NODE_PUBLIC_KEY - Env: KEYCHAIN_SUFFIX_PUBLIC_KEY - CLI: --keychain-suffix-public-key - - -``` - -##### 5.4.1.1.3 Plugin Loading/Validation - -Plugin loading happens through NodeJS's built-in module loader and the validation is performed by the Node Package Manager tool (npm) which verifies the byte level integrity of all installed modules. - -#### 5.4.1.2 core-api - -Contains interface definitions for the plugin architecture and other system level components that are to be shared among many other packages. -`core-api` is intended to be a leaf package meaning that it shouldn't depend on other packages in order to make it safe for any and all packages to depend on `core-api` without having to deal with circular dependency issues. - -#### 5.4.1.3 API Client - -Javascript API Client (bindings) for the RESTful HTTP API provided by `cmd-api-server`. -Compatible with both NodeJS and Web Browser (HTML 5 DOM + ES6) environments. - -#### 5.4.1.4 keychain - -Responsible for persistently storing highly sensitive data (e.g. private keys) in an encrypted format. - -For further details on the API surface, see the relevant section under `Plugin Architecture`. - -#### 5.4.1.5 tracing - -Contains components for tracing, logging and application performance management (APM) of code written for the rest of the Hyperledger Cactus packages. - -#### 5.4.1.6 audit - -Components useful for writing and reading audit records that must be archived longer term and immutable. -The latter properties are what differentiates audit logs from tracing/logging messages which are designed to be ephemeral and to support technical issues not regulatory/compliance/governance related issues. - -#### 5.4.1.7 document-storage - -Provides structured or unstructured document storage and analytics capabilities for other packages such as `audit` and `tracing`. -Comes with its own API surface that serves as an adapter for different storage backends via plugins. -By default, `Open Distro for ElasticSearch` is used as the storage backend: https://aws.amazon.com/blogs/aws/new-open-distro-for-elasticsearch/ - - - -> The API surface provided by this package is kept intentionally simple and feature-poor so that different underlying storage backends remain an option long term through the plugin architecture of `Cactus`. - -#### 5.4.1.8 relational-storage - -Contains components responsible for providing access to standard SQL compliant persistent storage. - -> The API surface provided by this package is kept intentionally simple and feature-poor so that different underlying storage backends remain an option long term through the plugin architecture of `Cactus`. - -#### 5.4.1.9 immutable-storage - -Contains components responsible for providing access to immutable storage such as a distributed ledger with append-only semantics such as a blockchain network (e.g. Hyperledger Fabric). - -> The API surface provided by this package is kept intentionally simple and feature-poor so that different underlying storage backends remain an option long term through the plugin architecture of `Cactus`. - -### 5.4.2 Deployment Diagram - -Source file: `./docs/architecture/deployment-diagram.puml` - - - -### 5.4.3 Component Diagram - - - -### 5.4.4 Class Diagram - -### 5.4.5 Sequence Diagram - Transactions - -TBD - -
- -## 5.5 Transaction Protocol Specification - -### 5.5.1 Handshake Mechanism - -TBD - -### 5.5.2 Transaction Protocol Negotiation - -Participants in the transaction must have a handshake mechanism where they agree on one of the supported protocols to use to execute the transaction. The algorithm looks an intersection in the list of supported algorithms by the participants. - -Participants can insist on a specific protocol by pretending that they only support said protocol only. -Protocols can be versioned as the specifications mature. -Adding new protocols must be possible as part of the plugin architecture allowing the community to propose, develop, test and release their own implementations at will. -The two initially supported protocols shall be the ones that can satisfy the requirements for Fujitsu’s and Accenture’s implementations respectively. -Means for establishing bi-directional communication channels through proxies/firewalls/NAT wherever possible - -
- -## 5.6 Plugin Architecture - -Since our goal is integration, it is critical that `Cactus` has the flexibility of supporting most ledgers, even those that don't exist today. - -> A plugin is a self contained piece of code that implements a predefined interface pertaining to a specific functionality of `Cactus` such as transaction execution. - -Plugins are an abstraction layer on top of the core components that allows operators of `Cactus` to swap out implementations at will. - -> Backward compatibility is important, but versioning of the plugins still follows the semantic versioning convention meaning that major upgrades can have breaking changes. - -Plugins are implemented as ES6 modules (source code) that can be loaded at runtime from the persistent data store. The core package is responsible for validating code signatures to guarantee source code integrity. - -An overarching theme for all aspects that are covered by the plugin architecture is that there should be a dummy implementation for each aspect to allow the simplest possible deployments to happen on a single, consumer grade machine rather than requiring costly hardware and specialized knowledge. - -> Ideally, a fully testable/operational (but not production ready) `Cactus` deployment could be spun up on a developer laptop with a single command (an npm script for example). - ---- - - - ---- - -### 5.6.1 Ledger Connector Plugins - -Success is defined as: -1. Adding support in `Cactus` for a ledger invented in the future requires no `core` code changes, but instead can be implemented by simply adding a corresponding connector plugin to deal with said newly invented ledger. -2. Client applications using the REST API and leveraging the feature checks can remain 100% functional regardless of the number and nature of deployed connector plugins in `Cactus`. For example: a generic money sending application does not have to hardcode the supported ledgers it supports because the unified REST API interface (fed by the ledger connector plugins) guarantees that supported features will be operational. - -Because the features of different ledgers can be very diverse, the plugin interface has feature checks built into allowing callers/client applications to **determine programmatically, at runtime** if a certain feature is supported or not on a given ledger. - -```typescript -export interface LedgerConnector { - // method to verify a signature coming from a given ledger that this connector is responsible for connecting to. - verifySignature(message, signature): Promise; - - // used to call methods on smart contracts or to move assets between wallets - transact(transactions: Transaction[]); - - getPermissionScheme(): Promise; - - getTransactionFinality(): Promise; - - addForeignValidator(): Promise; -} - -export enum TransactionFinality { - GUARANTEED = "GUARANTEED", - NOT_GUARANTEED = "NOT_GUARANTEED" -} - -export enum PermissionScheme { - PERMISSIONED = "PERMISSIONED", - PERMISSIONLESS = "PERMISSIONLESS" -} - -``` -#### 5.6.1.1 Ledger Connector Besu Plugin - -This plugin provides `Cactus` a way to interact with Besu networks. Using this we can perform: -* Deploy Smart-contracts through bytecode. -* Build and sign transactions using different keystores. -* Invoke smart-contract functions that we have deployed on the network. - -#### 5.6.1.2 Ledger Connector Connector Corda - -This plugin provides `Cactus` a way to interact with Corda networks. Using this we can perform: -* Deploy mentioned JVM application in addition to the Cactus API server with the desired plugins configured. -* Invoke contract flow with different kinds of parameters - -#### 5.6.1.3 Ledger Connector Fabric Socketio - -This plugin provides `Cactus` a way to interact with Hyperledger Fabric networks. Using this we can perform: -* `sendSyncRequest`: Send sync-typed requests to the ledgers (e.g. getBalance) -* `sendAsyncRequest`: Send async-typed requests to the ledgers (e.g. sendTransaction) -* `startMonitor`: Start monitoring blocks on the ledgers -* `stopMonitor`: Stop the block monitoring - -#### 5.6.1.4 Ledger Connector Fabric Plugin - -This plugin provides `Cactus` a way to interact with Fabric networks. Using this we can perform: -* Deploy Golang chaincodes. -* Execute transactions on the ledger. -* Invoke chaincodes functions that we have deployed on the network. - -#### 5.6.1.5 Ledger Connector Go Ethereum Socketio - -This plugin provides `Cactus` a way to interact with Go-Ethereum networks. Using this we can perform: -* `sendSyncRequest`: Send sync-typed requests to the ledgers (e.g. getBalance) -* `sendAsyncRequest`: Send async-typed requests to the ledgers (e.g. sendTransaction) -* `startMonitor`: Start monitoring blocks on the ledgers -* `stopMonitor`: Stop the block monitoring - -#### 5.6.1.6 Ledger Connector Iroha Plugin - -This plugin provides `Cactus` a way to interact with Iroha networks. Using this we can perform: -* Run various Iroha leger commands and queries. -* Build and sign transactions using any arbitrary credential. - -#### 5.6.1.7 Ledger Connector Quorum Plugin - -This plugin provides `Cactus` a way to interact with Quorum networks. Using this we can perform: -* Deploy Smart-contracts through bytecode. -* Build and sign transactions using different keystores. -* Invoke smart-contract functions that we have deployed on the network. - -#### 5.6.1.8 Ledger Connector Sawtooth Socketio Plugin - -This plugin provides `Cactus` a way to interact with Hyperledger Sawtooth. Using this we can perform: -* `startMonitor`: Start monitoring blocks on the ledgers -* `stopMonitor`: Stop the block monitoring - -#### 5.6.1.9 Ledger Connector Xdai Plugin - -This plugin provides `Cactus` a way to interact with Xdai networks. Using this we can perform: -* Deploy Smart-contracts through bytecode. -* Build and sign transactions using different keystores. -* Invoke smart-contract functions that we have deployed on the network. - - -### 5.6.2 HTLCs Plugins - -Provides an API to deploy and interact with Hash Time Locked Contracts (HTLC), used for the exchange of assets in different blockchain networks. -HTLC use hashlocks and timelocks to make payments. Requires that the receiver of a payment acknowledge having received this before a deadline or he will lose the ability to claim payment, returning this to rhe payer. - -#### 5.6.2.1 HTLC-ETH-Besu Plugin - -For the network Besu case, this plugin uses [Leger Connector Besu Plugin](#5611-ledger-connector-besu-plugin) to deploy an HTLC contract on the network and provides an API to interact with the HTLC ETH swap contracts. - -#### 5.6.2.2 HTLC-ETH-ERC20-Besu Plugin -For the network Besu case, this plugin uses [Leger Connector Besu Plugin](#5611-ledger-connector-besu-plugin) to deploy an HTLC and ERC20 contract on the network and provides an API to interact with this. -This plugin allow `Cactus` to interact with ERC-20 tokens in HTLC ETH swap contracts. - -### 5.6.3 Identity Federation Plugins - -Identity federation plugins operate inside the API Server and need to implement the interface of a common PassportJS Strategy: -https://github.com/jaredhanson/passport-strategy#implement-authentication - -```typescript -abstract class IdentityFederationPlugin { - constructor(options: any): IdentityFederationPlugin; - abstract authenticate(req: ExpressRequest, options: any); - abstract success(user, info); - abstract fail(challenge, status); - abstract redirect(url, status); - abstract pass(); - abstract error(err); -} -``` - -#### 5.6.3.1 X.509 Certificate Plugin - -The X.509 Certificate plugin facilitates clients authentication by allowing them to present a certificate instead of operating with authentication tokens. -This technically allows calling clients to assume the identities of the validator nodes through the REST API without having to have access to the signing private key of said validator node. - -PassportJS already has plugins written for client certificate validation, but we go one step further with this plugin by providing the option to obtain CA certificates from the validator nodes themselves at runtime. - -### 5.6.4 Key/Value Storage Plugins - -Key/Value Storage plugins allow the higher-level packages to store and retrieve configuration metadata for a `Cactus` cluster such as: -* Who are the active validators and what are the hosts where said validators are accessible over a network? -* What public keys belong to which validator nodes? -* What transactions have been scheduled, started, completed? - -```typescript -interface KeyValueStoragePlugin { - async get(key: string): Promise; - async set(key: string, value: T): Promise; - async delete(key: string): Promise; -} -``` - -### 5.6.5 Serverside Keychain Plugins - -The API surface of keychain plugins is roughly the equivalent of the key/value *Storage* plugins, but under the hood these are of course guaranteed to encrypt the stored data at rest by way of leveraging storage backends purpose built for storing and managing secrets. - -Possible storage backends include self hosted software [1] and cloud native services [2][3][4] as well. The goal of the keychain plugins (and the plugin architecture at large) is to make `Cactus` deployable in different environments with different backing services such as an on-premise data center or a cloud provider who sells their own secret management services/APIs. -There should be a dummy implementation as well that stores secrets in-memory and unencrypted (strictly for development purposes of course). The latter will decrease the barrier to entry for new users and would be contributors alike. - -Direct support for HSM (Hardware Security Modules) is also something the keychain plugins could enable, but this is lower priority since any serious storage backend with secret management in mind will have built-in support for dealing with HSMs transparently. - -By design, the keychain plugin can only be used by authenticated users with an active `Cactus` session. Users secrets are isolated from each other on the keychain via namespacing that is internal to the keychain plugin implementations (e.g. users cannot query other users namespaces whatsoever). - -```typescript -interface KeychainPlugin extends KeyValueStoragePlugin { -} -``` - -[1] https://www.vaultproject.io/ -[2] https://aws.amazon.com/secrets-manager/ -[3] https://aws.amazon.com/kms/ -[4] https://azure.microsoft.com/en-us/services/key-vault/ - -
- -### 5.6.6 Manual Consortium Plugin - -This plugin is the default/simplest possible implementation of consortium management. -It delegates the initial trust establishment to human actors to be done manually or offline if you will. - -Once a set of members and their nodes were agreed upon, a JSON document containing the consortium metadata can be -constructed which becomes an input parameter for the `cactus-plugin-consortium-manual` package's implementation. -Members bootstrap the consortium by configuring their Cactus nodes with the agreed upon JSON document and start their -nodes. -Since the JSON document is used to generate JSON Web Signatures (JWS) as defined by -[RFC 7515](https://tools.ietf.org/html/rfc7515#section-7.2) it is important that every consortium member uses the same -JSON document representing the consortium. - -> Attention: JWS is not the same as JSON Web Tokens (JWT). JWT is an extension of JWS and so they can seem very similar -> or even indistinguishable, but it is actually two separate things where JWS is the lower level building block that -> makes JWT's higher level use-cases possible. This is not related to Cactus itself, but is important to be mentioned -> since JWT is very well known among software engineers while JWS is a much less often used standard. - -Example of said JSON document (the `"consortium"` property) as passed in to the plugin configuration can be -seen below: - -```json -{ - "packageName": "@hyperledger/cactus-plugin-consortium-manual", - "options": { - "consortium": { - "name": "Example Cactus Consortium", - "id": "2ae136f6-f9f7-40a2-9f6c-92b1b5d5046c", - "mainApiHost": "http://127.0.0.1:4000", - "members": [ - { - "id": "b24f8705-6da5-433a-b8c7-7d2079bae992", - "name": "Example Cactus Consortium Member 1", - "nodes": [ - { - "nodeApiHost": "http://127.0.0.1:4000", - "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAEtDeq7BgpelfsX7WKiSb7Lhxp8VeS6YY/\nInbYuTgwZ8ykGs2Am2fM03aeMX9pYEzaeOVRU6ptwaEBFYX+YftCSQ==\n-----END PUBLIC KEY-----\n" - } - ] - } - ] - } - } - } -``` - -The configuration above will cause the `Consortium JWS` REST API endpoint (callable via the API Client) to respond with a -consortium JWS that looks similar to what is pasted below. - -Code examples of how to use the API Client to call this endpoint can be seen at -`./packages/cactus-cockpit/src/app/consortium-inspector/consortium-inspector.page.ts` - -```json -{ - "payload": "eyJjb25zb3J0aXVtIjp7ImlkIjoiMmFlMTM2ZjYtZjlmNy00MGEyLTlmNmMtOTJiMWI1ZDUwNDZjIiwibWFpbkFwaUhvc3QiOiJodHRwOi8vMTI3LjAuMC4xOjQwMDAiLCJtZW1iZXJzIjpbeyJpZCI6ImIyNGY4NzA1LTZkYTUtNDMzYS1iOGM3LTdkMjA3OWJhZTk5MiIsIm5hbWUiOiJFeGFtcGxlIENhY3R1cyBDb25zb3J0aXVtIE1lbWJlciAxIiwibm9kZXMiOlt7Im5vZGVBcGlIb3N0IjoiaHR0cDovLzEyNy4wLjAuMTo0MDAwIiwicHVibGljS2V5UGVtIjoiLS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS1cbk1GWXdFQVlIS29aSXpqMENBUVlGSzRFRUFBb0RRZ0FFdERlcTdCZ3BlbGZzWDdXS2lTYjdMaHhwOFZlUzZZWS9cbkluYll1VGd3Wjh5a0dzMkFtMmZNMDNhZU1YOXBZRXphZU9WUlU2cHR3YUVCRllYK1lmdENTUT09XG4tLS0tLUVORCBQVUJMSUMgS0VZLS0tLS1cbiJ9XX1dLCJuYW1lIjoiRXhhbXBsZSBDYWN0dXMgQ29uc29ydGl1bSJ9fQ", - "signatures": [ - { - "protected": "eyJpYXQiOjE1OTYyNDQzMzQ0NTksImp0aSI6IjM3NmJjMzk0LTBlYWMtNDcwZi04NjliLThkYWIzNDRmNmY3MiIsImlzcyI6Ikh5cGVybGVkZ2VyIENhY3R1cyIsImFsZyI6IkVTMjU2SyJ9", - "signature": "ltnDyOe9WSdCk6f5Op8XlcnFoXUp3yJZgImsAvERnxWM-eeL6eX0MnCtfC5r3q6knt4kTTaUv8536SMCka_YyA" - } - ] -} -``` - -The same JWS after being decoded looks like this: - -```json -{ - "payload": { - "consortium": { - "id": "2ae136f6-f9f7-40a2-9f6c-92b1b5d5046c", - "mainApiHost": "http://127.0.0.1:4000", - "members": [ - { - "id": "b24f8705-6da5-433a-b8c7-7d2079bae992", - "name": "Example Cactus Consortium Member 1", - "nodes": [ - { - "nodeApiHost": "http://127.0.0.1:4000", - "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAEtDeq7BgpelfsX7WKiSb7Lhxp8VeS6YY/\nInbYuTgwZ8ykGs2Am2fM03aeMX9pYEzaeOVRU6ptwaEBFYX+YftCSQ==\n-----END PUBLIC KEY-----\n" - } - ] - } - ], - "name": "Example Cactus Consortium" - } - }, - "signatures": [ - { - "protected": { - "iat": 1596244334459, - "jti": "376bc394-0eac-470f-869b-8dab344f6f72", - "iss": "Hyperledger Cactus", - "alg": "ES256K" - }, - "signature": "ltnDyOe9WSdCk6f5Op8XlcnFoXUp3yJZgImsAvERnxWM-eeL6eX0MnCtfC5r3q6knt4kTTaUv8536SMCka_YyA" - } - ] -} -``` - -The below sequence diagram demonstrates a real world example of how a consortium between two business organizations (who both -operate their own distributed ledgers) can be formed manually and then operated through the plugin discussed here. -There's many other ways to perform the initial agreement that happens offline, but a concrete, non-generic example is -provided here for ease of understanding: - - - -### 5.6.7 Test Tooling - -Provides `Cactus` with a tool to test the different plugins of the project. - - -# 6. Identities, Authentication, Authorization - -`Cactus` aims to provide a unified API surface for managing identities of an identity owner. -Developers using the `Cactus` Service API for their applications can support one or both of the below requirements: -1. Applications with a focus on access control and business process efficiency (usually in the enterprise) -2. Applications with a focus on individual privacy (usually consumer-based applications) - -The following sections outline the high-level features of `Cactus` that make the above vision reality. - -An end user (through a user interface) can issue API requests to -* register a username+password account (with optional MFA) **within** `Cactus`. -* associate their wallets to their `Cactus` account and execute transactions involving those registered wallet (transaction signatures performed either locally or remotely as explained above). -* execute a trade which executes a set of transactions across integrated Ledgers. `Cactus` may also executes recovery transaction(s) when the trade was failed with some reason. For example, recovery transactions may be executed to reverse executed transaction result using intermediate account which provide escrow trading service. - -## 6.1 Definition of Identities in Cactus - -Various identities are used at Cactus Service API. - -**Cactus user ID** -* ID for user (behind web service application) to execute a Service API call. -* Service provider assign the role(s) and access right(s) of user in integrated service as part of `Business Logic Plugin`. -* The user can add Wallet(s) which is associated with account address and/or key. - -**Wallet ID** -* ID for the user identity which is associated with authentication credential at integrated `Ledger`. -* It is recommended to store temporary credential here allowing minimal access to operate `Ledger` instead of giving full access with primary secret. -* Service API enables user to add/update/delete authentication credential for the Wallet. - -**Ledger ID** -* ID for `Ledger Plugin` which is used at Wallet -* `Ledger ID` is assigned by administrator of integrated service, and provided for user to configure their own Wallet settings. -* The connectivity settings associated with the `Ledger ID` is also configured at `Ledger Plugin` by the administrator. - -**Business Logic ID** -* ID for business logic to be invoked by Cactus user. -* Each business logic should be implemented to execute necessary transactions on integrated `Ledgers` without any interaction with user during its execution. -* Business logic may require user to setup access permission with storing credential before executing business logic call. - - -## 6.2 Transaction Signing Modes, Key Ownership - -An application developer using `Cactus` can choose to enable users to sign their transactions locally on their user agent device without disclosing their private keys to `Cactus` or remotely where `Cactus` stores private keys server-side, encrypted at rest, made decryptable through authenticating with their `Cactus` account. -Each mode comes with its own pros and cons that need to be carefully considered at design time. - -### 6.2.1 Client-side Transaction Signing - -Usually a better fit for consumer-based applications where end users have higher expectation of individual privacy. - -**Pros** -* Keys are not compromised when a `Cactus` deployment is compromised -* Operator of `Cactus` deployment is not liable for breach of keys (same as above) -* Reduced server-side complexity (no need to manage keys centrally) - -**Cons** -* User experience is sub-optimal compared to sever side transaction signing -* Users can lose access permanently if they lose the key (not acceptable in most enterprise/professional use cases) - ---- - - - ---- - -### 6.2.2 Server-side Transaction Signing - -Usually a better fit for enterprise applications where end users have most likely lowered their expectations of individual privacy due to the hard requirements of compliance, governance, internal or external policy enforcement. - -**Pros** -* Frees end users from the burden of managing keys themselves (better user experience) - * Improved compliance, governance - -**Cons** -* Server-side breach can expose encrypted keys stored in the keychain - ---- - - - ---- - -## 6.3 Open ID Connect Provider, Identity Provider - -`Cactus` can authenticate users against *third party Identity Providers* or serve as an *Identity Provider* itself. -Everything follows the well-established industry standards of Open ID Connect to maximize information security and reduce the probability of data breaches. - -## 6.4 Server-side Keychain for Web Applications - -There is a gap between traditional web/mobile applications and blockchain applications (web 2.0 and 3.0 if you will) authentication protocols in the sense that blockchain networks rely on private keys belonging to a Public Key Infrastructure (PKI) to authenticate users while traditional web/mobile applications mostly rely on a centralized authority storing hashed passwords and the issuance of ephemeral tokens upon successful authentication (e.g. successful login with a password). -Traditional (Web 2.0) applications (that adhering security best practices) use server-side sessions (web) or secure keychains provided by the operating system (iOS, Android, etc.) -The current industry standard and state of the art authentication protocol in the enterprise application development industry is Open ID Connect (OIDC). - -To successfully close the gap between the two worlds, `Cactus` comes equipped with an OIDC identity provider and a server-side key chain that can be leveraged by end user applications to authenticate once against Hyperledger Cactus and manage identities on other blockchains through that single Hyperledger Cactus identity. -This feature is important for web applications which do not have secure offline storage APIs (HTML localStorage is not secure). - -Example: A user can register for a Hyperledger Cactus account, import their private keys from their Fabric/Ethereum wallets and then have access to all of those identities by authenticating once only against `Cactus` which will result in a server-side session (HTTP cookie) containing a JSON Web Token (JWT). - -> Native mobile applications may not need to use the server-side keychain since they usually come equipped with an OS provided one (Android, iOS does). - - - -In web 2.0 applications the prevalent authentication/authorization solution is Open ID Connect which bases authentication on passwords and tokens which are derived from the passwords. -Web 3.0 applications (decentralized apps or *DApps*) which interact with blockchain networks rely on private keys instead of passwords. - -
- -# 7. Terminology - -**Application user**: The user who requests an API call to a Hyperledger Cactus application or smart contract. The API call triggers the sending of the transaction to the remote ledger. - -**Hyperledger Cactus Web application or Smart contract on a blockchain**: The entity executes business logic and provide integration services that include multiple blockchains. - -**Tx verifier**: The entity verifies the signature of the transaction data transmitted over the secure bidirectional channel. Validated transactions are processed by the Hyperledger Cactus Web application or Smart Contract to execute the integrated business logic. - -**Tx submitter**: The entity submits the remote transaction to the API server plug-in on one of the ledgers. - -**API Server**: A Cactus package that is the backbone of the plugin architecture and the host component for all plugins with the ability to automatically wire up plugins that come with their own web services (REST or asynchronous APIs through HTTP or WebSockets for example) - -**Cactus Node**: A set of identically configured API servers behind a single network host where the set size is customizable from 1 to infinity with the practical maximum being much lower of course. This logical distinction between node and API server is important because it allows consortium members to abstract away their private infrastructure details from the public consortium definition. - -For example if a consortium member wants to have a highly available, high throughput service, they will be forced to run a cluster of API servers behind a load balancer and/or reverse proxy to achieve these system properties and their API servers may also be in an auto-scaling group of a cloud provider or (in the future) even run as Lambda functions. To avoid having to update the consortium definition (which requires a potentially costly consensus from other members) every time let's say an auto-scaling group adds a new API server to a node, the consortium member can define their presence in the consortium by declaring a single `Cactus Node` and then customize the underlying deployment as they see fit so long as they ensure that the previously agreed upon keys are used by the node and it is indeed accessible through the network host as declared by the `Cactus Node`. -To get a better understanding of the various, near-infinite deployment scenarios, head over to the [Deployment Scenarios](#57-deployment-scenarios) sub-section of the [Architecture](#5-architecture) top level section. - -**Validator**: A module of Hyperledger Cactus which verifies validity of transaction to be sent out to the blockchain application. - -**Lock asset**: An operation to the asset managed on blockchain ledger, which disable further operation to targeted asset. The target can be whole or partial depends on type of asset. - -**Abort**: A state of Hyperledger Cactus which is determined integrated ledger operation is failed, and Hyperledger Cactus will execute recovery operations. - -**Integrated ledger operation**: A series of blockchain ledger operations which will be triggered by Hyperledger Cactus. Hyperledger Cactus is responsible to execute 'recovery operations' when 'Abort' is occurred. - -**Restore operation(s)**: Single or multiple ledger operations which is executed by Hyperledger Cactus to restore the state of integrated service before start of integrated operation. - -**End User**: A person (private citizen or a corporate employee) who interacts with Hyperledger Cactus and other ledger-related systems to achieve a specific goal or complete a task such as to send/receive/exchange money or data. - -**Business Organization**: A for-profit or non-profit entity formed by one or more people to achieve financial gain or achieve a specific (non-financial) goal. For brevity, *business organization* may be shortened to *organization* throughout the document. - -**Identity Owner**: A person or organization who is in control of one or more identities. For example, owning two separate email accounts by one person means that said person is the identity owner of two separate identities (the email accounts). Owning cryptocurrency wallets (their private keys) also makes one an identity owner. - -**Identity Secret**: A private key or a password that - by design - is only ever known by the identity owner (unless stolen). - -**Credentials**: Could mean `user a` authentication credentials/identity proofs in an IT application or any other credentials in the traditional sense of the word such as a proof that a person obtained a bachelor's degree or a PhD. - -**Ledger/Network/Chain**: Synonymous words meaning referring largely to the same thing in this paper. - -**OIDC**: Open ID Connect authentication protocol - -**PKI**: Public Key Infrastructure - -**MFA**: Multi Factor Authentication - -
- -# 8. Related Work -Blockchain interoperability is emerging as one of the crucial features of blockchain technology -A recent survey classifies blockchain interoperability studies in three categories: Cryptocurrency-directed interoperability approaches, Blockchain Engines, and Blockchain Connectors [[5](#8-references)]. Each category is further divided into sub-categories based on defined criteria. -Each category serves particular use cases. - -![rw](./related-work-categories.png) - - -Cryptocurrency-directed interoperability approaches identify and define different strategies for chain interoperability across public blockchains, most of them implementing cryptocurrencies. - -Blockchain engines are frameworks that provide reusable data, network, consensus, incentive, and contract layers for the creation of customized blockchains, serving general use-cases. Emerging blockchains are, for example, the Cosmos Network and Polkadot. - -The Blockchain Connector category is composed of interoperability solutions that are not cryptocurrency-directed or blockchain engines. Several sub-categories exist: Trusted Relays, Blockchain Agnostic Protocols, Blockchain of Blockchains, and Blockchain Migrators”. - -While Hyperledger Cactus has caracteristics from the the three categories, it can be considered a Blockchain Connector (namely a Trusted Relay). In particular, Cactus focuses on providing multiple use case scenarios via a trusted consortium. -Trusted relays allow the discovery of the target blockchains, appearing often in a permissioned blockchain environment, where cross-blockchain transactions are routed by trusted escrow parties. Thus, Cactus supports developers at building cross-chain dApps. - -Depending on the validator plugin, the trust on the relay can be decentralized, making Cactus a decentralized, general-purpose, trustless relay. -The blockchain migrator feature paves the way for building a solution that performs data migration across blockchains. - -# 9. References - -1: [Heterogeneous System Architecture](https://en.wikipedia.org/wiki/Heterogeneous_System_Architecture) - Wikipedia, Retrieved at: 11th of December 2019 - -2: E Scheid and Burkhard Rodrigues, B Stiller. 2019. Toward a policy-based blockchain agnostic framework. 16th IFIP/IEEE International Symposium on Integrated Network Management (IM 2019) (2019) - -3: Philipp Frauenthaler, Michael Borkowski, and Stefan Schulte. 2019. A Framework for Blockchain Interoperability and Runtime Selection. - -4: H.M.N. Dilum Bandara, Xiwei Xu, and Ingo Weber. 2020. [Patterns for blockchain data migration](https://arxiv.org/abs/1906.00239). European Conf. on Pattern Languages of Programs 2020 (EuroPLoP 2020). - -5: Rafael Belchior, André Vasconcelos, Sérgio Guerreiro, and Miguel Correia. 2021. A Survey on Blockchain Interoperability: Past, Present, and Future Trends. ACM Comput. Surv. 54, 8, Article 168 (November 2022), 41 pages. DOI:https://doi.org/10.1145/3471140 - -6: Belchior, Rafael; Riley, Luke; Hardjono, Thomas; Vasconcelos, André; Correia, Miguel (2022): Do You Need a Distributed Ledger Technology Interoperability Solution?. TechRxiv. Preprint. https://doi.org/10.36227/techrxiv.18786527.v1 - -7: Rafael Belchior, André Vasconcelos, Miguel Correia, Thomas Hardjono, Hermes: Fault-tolerant middleware for blockchain interoperability, -Future Generation Computer Systems, -Volume 129, 2022, Pages 236-251 - -
- -# 10. Recommended Reference -Please use the following BibTex entry to cite this whitepaper: - -@report{montgomery_hyperledger_2022, - title = {Hyperledger Cactus Whitepaper}, - url = {https://github.com/hyperledger/cactus/blob/main/docs/whitepaper/whitepaper.md}, - number = {2}, - institution = {Hyperledger}, - author = {Montgomery, Hart and Borne-Pons, Hugo and Hamilton, Jonathan and Bowman, Mic and Somogyvari, Peter and Fujimoto, Shingo and Takeuchi, Takuma and Kuhrt, Tracy and Belchior, Rafael}, - date = {2022}, -} \ No newline at end of file +> # ⚠️ +> # 👷🚧🏗️ +> +> +> The whitepaper is currently under construction. +> +> Please see the related item in the issue tracker for further details & to join the discussion/work: +> https://github.com/hyperledger/cacti/issues/2691 +> +> To access the old version of the whitepaper, you can use +> an older commit of the `main` branch, such as this one: +> https://github.com/hyperledger/cacti/blob/7bb39576080592919bea0ac89646b32105e1748e/whitepaper/whitepaper.md diff --git a/whitepaper/whitepaper_zh-CN.md b/whitepaper/whitepaper_zh-CN.md deleted file mode 100644 index 06479fef18..0000000000 --- a/whitepaper/whitepaper_zh-CN.md +++ /dev/null @@ -1,887 +0,0 @@ - - -# Hyperledger Cactus
白皮书 - -本译文基于 https://github.com/hyperledger/cactus CommitID：d0b47d2e5afa65638c6bbd1e0737d4116f073654 - -## Version 0.1 (Early Draft) - - -Photo by Pontus Wellgraf on Unsplash - -
- -# 贡献者 - -| Contributors/Reviewers | Email | -|--------------------------------|-------------------------------------------| -| Hart Montgomery | hmontgomery@us.fujitsu.com | -| Hugo Borne-Pons | hugo.borne-pons@accenture.com | -| Jonathan Hamilton | jonathan.m.hamilton@accenture.com | -| Mic Bowman | mic.bowman@intel.com | -| Peter Somogyvari | peter.somogyvari@accenture.com | -| Shingo Fujimoto | shingo_fujimoto@fujitsu.com | -| Takuma Takeuchi | takeuchi.takuma@fujitsu.com | -| Tracy Kuhrt | tracy.a.kuhrt@accenture.com | -| Rafael Belchior | rafael.belchior@tecnico.ulisboa.pt | - -# 翻译者 - -| Translators/Reviewers | Email | -| --------------------- | ----------------------- | -| Yang Cheng | chengyang418@163.com | -| Yuxiang Liu | david-khala@hotmail.com | - -# 历史版本 - -| Date of Revision | Description of Changes Made | -|-----------------------|--------------------------------------------------------| -| February 2020 | Initial draft | - -
- -- [1. 概述](#1-概述) -- [2. 使用案例](#2-使用案例) - - [2.1 Ethereum 到 Quorum 的资产转移](#21-ethereum-到-quorum-的资产转移) - - [2.2 数据托管出售](#22-数据托管出售) - - [2.3 货币兑换](#23-货币兑换) - - [2.4 稳定币和其他货币的铆定](#24-稳定币和其他货币的铆定) - - [2.4.1 和非授权区块链兑换](#241-和非授权区块链兑换) - - [2.4.2 和法定货币兑换](#242-和法定货币兑换) - - [2.5 带有访问控制列表的医疗保健数据共享](#25-带有访问控制列表的医疗保健数据共享) - - [2.6 集成现有的食品溯源解决方案](#26-集成现有的食品溯源解决方案) - - [2.7 终端用户钱包身份验证/授权](#27-终端用户钱包身份验证授权) - - [2.8 区块链迁移](#28-区块链迁移) - - [2.8.1 区块链数据迁移](#281-区块链数据迁移) - - [2.8.2 区块链智能合约迁移](#282-区块链智能合约迁移) - - [2.8.3 半自动区块链迁移](#283-半自动区块链迁移) -- [3. 软件设计](#3-软件设计) - - [3.1. 原则](#31-原则) - - [3.1.1. 广泛的支持](#311-广泛的支持) - - [3.1.2. 尽可能的插件化架构](#312-尽可能的插件化架构) - - [3.1.3. 尽可能避免双花](#313-尽可能避免双花) - - [3.1.4 特性的包容性](#314-特性的包容性) - - [3.1.5 低影响](#315-低影响) - - [3.1.6 透明性](#316-透明性) - - [3.1.7 自动化的工作流](#317-自动化的工作流) - - [3.1.8 默认最高的安全性](#318-默认最高的安全性) - - [3.1.9 交易协议协商](#319-交易协议协商) - - [3.1.10 避免任何区块链网络上数字资产总量的变动的可能](#3110-避免任何区块链网络上数字资产总量的变动的可能) - - [3.1.11 提供通用操作的抽象](#3111-提供通用操作的抽象) - - [3.1.12 集成身份框架（Moonshot）](#3112-集成身份框架moonshot) - - [3.2 特性需求](#32-特性需求) - - [3.2.1 新协议的集成](#321-新协议的集成) - - [3.2.2 代理/防火墙/NAT 能力](#322-代理防火墙nat-能力) - - [3.2.3 双向通信层](#323-双向通信层) - - [3.2.4 联盟管理](#324-联盟管理) - - [3.3 工作策略](#33-工作策略) -- [4. 架构](#4-架构) - - [4.1 集成模式](#41-集成模式) - - [4.2 系统架构和基本流程](#42-系统架构和基本流程) - - [4.3 技术架构](#43-技术架构) - - [4.3.1 Monorepo包](#431-monorepo包) - - [4.3.1.1 cmd-api-server](#4311-cmd-api-server) - - [4.3.1.1.1 运行时配置解析和验证](#43111--运行时配置解析和验证) - - [4.3.1.1.2 配置模式 - API 服务器](#43112-配置模式---api-服务器) - - [4.3.1.1.4 插件加载/验证](#43114-插件加载验证) - - [4.3.1.2 core-api](#4312-core-api) - - [4.3.1.4 sdk](#4314-sdk) - - [4.3.1.5 密钥串（keychain）](#4315-密钥串keychain) - - [4.3.1.7 追溯](#4317-追溯) - - [4.3.1.8 审核](#4318-审核) - - [4.3.1.9 文档存储](#4319-文档存储) - - [4.3.1.10 相关存储](#43110-相关存储) - - [4.3.1.11 不可篡改存储](#43111-不可篡改存储) - - [4.3.2 部署图](#432-部署图) - - [4.3.3 组件图](#433-组件图) - - [4.3.4 类图](#434-类图) - - [4.3.5 时序图——交易](#435-时序图交易) - - [4.4 交易协议说明](#44-交易协议说明) - - [4.4.1 握手机制](#441-握手机制) - - [4.4.2 交易协议协商](#442-交易协议协商) - - [4.5 插件架构](#45-插件架构) - - [4.5.1 账本连接器插件](#451-账本连接器插件) - - [4.5.2 身份联盟插件](#452-身份联盟插件) - - [4.5.1.1 X.509证书插件](#4511-x509证书插件) - - [4.5.3 Key/Value 存储插件](#453-keyvalue-存储插件) - - [4.5.4 服务端密钥串插件](#454-服务端密钥串插件) -- [5. 身份、认证、授权](#5-身份认证授权) - - [5.1 交易签名模式、键所有权](#51-交易签名模式键所有权) - - [5.1.1 客户端交易签名](#511-客户端交易签名) - - [5.1.2 服务端交易签名](#512-服务端交易签名) - - [5.2 Open ID 链接提供者、身份提供者](#52-open-id-链接提供者身份提供者) - - [5.3 Web应用的服务端密钥串](#53-web应用的服务端密钥串) -- [6. 术语](#6-术语) -- [7. References 参考文献](#7-references-参考文献) - -
- -# 1. 概述 - -区块链技术的应用正在快速增长，但是碎片化可能是未来阻碍区块链应用的一个大问题。 - -我们提出了一个协议，并根据一个异构系统架构[1](#7-references)进行了实现以便连接尽可能多的区块链系统，以此来解决碎片化的问题。 - -# 2. 使用案例 - -我们的目的是支持特定使用场景。核心思想是通过多种账本的互操作性支持尽可能多的使用场景，特别是一些主流或者其他的用例。 - -## 2.1 Ethereum 到 Quorum 的资产转移 - -| 用例属性名称 | 用例属性值 | -| ------------ | ------------------------------------------------------------ | -| 用例标题 | Ethereum 到 Quorum 的托管资产转移 | -| 用例 | 1. `用户 A` 在 Ethereum 账本上拥有一些资产
2. `用户 A` 让`交易员`交易 Ethereum 账本上的指定数量的资产，Quorum 账本接收资产。 | -| 互通模式 | 数值转移 | -| 社交类型 | 托管资产转移 | -| 描述 | 一个人（`用户 A`）在不同的账本（Ethereum，Quorum）上有多个账户，他希望按照一定汇率将 Ethereum 账本上的资产发送到 Quorum 账本上。只有当它成功的在 Quorum 账本上接收到转换的资产后交易员才可以接收到 Ethereum 上发送的资产。 | -| 参与者 | 1. `用户 A`：一个人或者实体在拥有账本上与之相关账户的资产。 | -| 参与者目标 | `用户 A` 失去 Ethereum 上发送的资产的所有权，但是得到 Quorum 上交换的资产数量的所有权。 | -| 成功情景 | 转移成功没有问题。资产在 Ethereum 和 Quorum 账本上都可用。 | -| 成功标准 | 成功转移资产到 Quorum。 | -| 失败标准 | 转移资产到 Quorum 失败。 | -| 前提条件 | 1. 已提供账本。
2.`用户 A` 和`交易员`都在账本上建立了身份。
3.`交易员`有权使用业务逻辑插件操作 Quorum 账本上的账户。
4.`用户 A` 可以访问部署的 Hyperledger Cactus。 | -| 备注 | | - - - -
- - -
- -## 2.2 数据托管出售 - - -| W3C 用例属性名称 | W3C 用例属性值 | -|-----------------------------|------------------------------------------------| -| 用例标题 | 数据托管出售 | -| 用例 | 1. `用户 A` 初始化（提案）一个和`用户 B`的托管交易。
2. `用户 A` 拿出资金，`用户 B` 拿出用于数字托管服务的数据。
3. 他们都观察到对方向托管服务的输入然后决定继续进行。
4. 托管服务释放资金和数据到交换的参与者。 | -| 社交类型 | 点对点交换 | -| 描述 | 在此场景中的数据是电脑中以比特形式存储的内容：
* 机器学习模型
* 广告技术数据库
* 数字或数字化的艺术
* 专有的软件源码或二进制
* 其他。

`用户 A` 和 B 使用 Hyperledger Cactus 交易数据和资金，交易以原子交换的托管方式进行，可以有效避免参会双方的欺诈或者交易失败。
通过交易协议的握手机制，A 和 B 可以（事先）同意：

* 交付地址（哪个账本，哪个钱包）
* 他们都信任的托管商
* 价格和货币类型

可以通过参与 DLT，如果他们支持的话，来促进信任的建立。注意，`用户 A` 没办法知道数据集的质量，他们完全依赖于`用户 B` 的描述（这个问题有一些解决方案，但那不在我们讨论的范围之内）。 | -| 参与者 | 1. `用户 A`：一个想要购买数据的人或者商业组织。
2. `用户 B`：一个想要出售数据的人或者商业实体。 | -| 参与者目标 | `用户 A` 想要获得数据的访问权，可能因为这些数据可以帮他增强业务过程。
`用户 B` 想要通过他们的拥有的数据产生利润。 | -| 成功情景 | 参与者都独立进行托管操作并且按预期完成交换。 | -| 成功标准 | `用户 A` 成功访问数据，`用户 B` 获得了资金。 | -| 失败标准 | 任何一个参与者没有完成他们最终的交易。 | -| 前提条件 | `用户 A` 有用于交易的资金。
`用户 B` 有 `用户 A` 想要的数据。
`用户 A` 和 B 同意以合适的货币进行交易并且和托管商达成共识。 | -| 备注 | Hyperledger 私有数据： https://hyperledger-fabric.readthedocs.io/en/release-1.4/private_data_tutorial.html
Besu 私有群组： https://besu.hyperledger.org/en/stable/Concepts/Privacy/Privacy-Groups/ | - -
- - -
- -## 2.3 货币兑换 - -使法定货币和虚拟货币能够以任何可能的组合进行交易。 - -> 在技术层面，该用例和上边的用例是一样的，但是我们省略了一些细节。 - -## 2.4 稳定币和其他货币的铆定 - - -| W3C 用例属性名称 | W3C 用例属性值 | -|-----------------------------|------------------------------------------------| -| 用例标题 | 稳定币和其他货币的铆定 | -| 用例 | 1. `用户 A` 创建他们自己的账本。
2. `用户 A` 在自己的环境中部署 Hyperledger Cactus。
3. `用户 A` 实现了 Hyperledger Cactus 必要的插件来对接他们账本的交易，代币产生和燃烧。 | -| 社交类型 | 软件实现项目 | -| 描述 | 有人启动了一个带有称为 ExampleCoin 代币的高可扩展账本，可以稳定保证每秒百万级别的交易吞吐，但是他们生存艰难，因为大家担心它的价值所以没有人愿意买他们的代币。他们选择与比特币建立一种双向锚定机制，向其持有者保证，他们的代币可以兑换成固定数量的比特币或美元。 | -| 参与者 | `用户 A`：账本和货币的所有者或者操作者，他们希望和其他货币保持稳定（锚定）。 | -| 参与者目标 | 1. 通过支持资金来获得他们货币的信誉。
2. 用最少的样板代码实现必要的软件（大部分应该由 Hyperldger Cactus 提供）。 | -| 成功情景 | `用户 A` 使用他们自己编写的插件来支持 Hyperledger Cactus 部署，终端用户应用程序开发可以从使用 Hyperledger Cactus REST API 开始，Hyperledger Cactus REST API 现在暴露了由`用户 A` 编写的插件所提供的功能。 | -| 成功标准 | 除了创建 Hyperledger Cactus 插件外，成功情景没有显著的额外开发工作。 | -| 失败标准 | 实现的复杂性很高，如果没有框架，从头开始写东西会更容易。 | -| 前提条件 | * 可操作性的账本和货币。
* 实现插件的技术知识（软件工程）。 | -| 备注 | | - -> 我们省略了时序图，因为该使用场景不适用于 Hyperledger Cactus 的终端用户。 - -### 2.4.1 和非授权区块链兑换 - -BTC 的持有者可以购买 ExampleCoin，购买方式是将他们的 BTC 发送到`保存 ExampleCoin 的钱包`，然后其他网络上就会挖出相应数量的代币发送到他们的 ExampleCoin 钱包。 - -ExampleCoin 的持有者可以将他们的资产兑换为 BTC，兑换方式是接收 ExampleCoin 账本上的燃烧证明（Proof of Burn），然后从`保存 ExampleCoin 的钱包`发送对应数量的 BTC 到他们的 BTC 钱包。 - - - -### 2.4.2 和法定货币兑换 - -和锚定 BTC 的想法非常相似，但是用来存储 BTC 的钱包换成了保存 USD 的传统银行账户。 - -
- -## 2.5 带有访问控制列表的医疗保健数据共享 - -| W3C 用例属性名称 | W3C 用例属性值 | -|-----------------------------|------------------------------------------------| -| 用例标题 | 带有访问控制列表的医疗保健数据共享 | -| 用例 | 1. `用户 A` （病人）和`用户 B`（医疗保健提供者） 建立业务关系。
2. `用户 B` 请求`用户 A` 的电子病历的读取和写入权限。
3. `用户 A` 接收到访问请求并通过。
4. `用户 B` 通过账本特定的访问控制或隐私特性得到获取 `用户 A` 数据的授权。 | -| 社交类型 | 点对点数据共享 | -| 描述 | 假设两个医疗保健提供商都实现了自己的基于区块链的患者数据管理系统，并希望彼此集成，以便为患者从一个到另一个医疗保健提供商进行某些治疗时提供无缝连接的体验。用户可以在两个平台上分别控制自己的数据，并且通过 Hyperledger Cactus 支持的集成，他们还可以定义细粒度的访问控制列表，同意两个医疗保健提供商访问彼此收集的有关患者的数据。 | -| 参与者 | * `用户 A`：和医疗保健提供者建立业务关系。
* `用户 B`：医疗保健提供者为`用户 A` 提供服务。其中一些服务依赖于`用户 A`之前病历的访问权限。 | -| 参与者目标 | * `用户 A`：想以更好地方式授权分享数据的数据，以免数据落入黑客之手或者流转到黑市中。
`用户 B` | -| 成功情景 | `用户 B`（医疗保健提供者）可以访问尽可能多的他们需要的数据，但是不能访问其他数据。 | -| 成功标准 | 有数据完整性的加密证明。数据在共享过程中没有受到损害，例如，其他参与者没有通过意外或恶意行为获得对数据的未经授权的访问。 | -| 失败标准 | `用户 B`（医疗保健提供者）没有访问所需数据的权限，或者有了不应访问的数据的权限。 | -| 前提条件 | `用户 A` 和`用户 B` 注册在同一个或两个单独的账本上，账本支持个人数据所有权、访问控制和共享的概念。 | -| 备注 | 如果`用户 A` 和`用户 B` 都在同一个授权的、支持隐私的账本上而不是在两个单独的账本上，那么最好的隐私更有意义。这为`用户 A` 提供了额外的安全层，因为他们可以知道他们的数据仍然只存储在一个账本上，而不是两个（尽管这两个账本都启用了隐私保护） | - - - - - -
- -## 2.6 集成现有的食品溯源解决方案 - -| W3C 用例属性名称 | W3C 用例属性值 | -| ---------------- | ------------------------------------------------------------ | -| 用例标题 | 食品溯源集成 | -| 用例 | 1. `消费者` 正在对实体零售店的食品进行评估。
2. `消费者`询问指定的提供食品轨迹的终端用户应用程序。
3. `消费者` 根据食物轨迹做出购买决定。 | -| 社交类型 | 软件实现项目 | -| 描述 | 零售商已从`组织 A` 购买食品溯源解决方案，而食品制造商（零售商是其客户）购买了`组织 B` 的食品溯源解决方案。
零售商希望向其客户提供端到端的食品溯源，但这是不可能的，因为溯源的链路在使用不同服务或解决方案的制造商处断开了。`Cactus` 被用作为零售商构建一个集成的架构组件，以确保消费者能够访问食品溯源数据，而不管其来源系统是`组织 A` 还是 `组织 B` 的产品或服务。 | -| 参与者 | `组织 A` ，`组织 B`，他们的业务涉及从种植或制造到消费者零售货架的食品全球供应链中的某些部分。
`消费者`：在消费品零售商店购买食品，并希望在最终确定购买决定之前对食品进行全程溯源的公民。 | -| 参与者目标 | `组织 A`，`组织 B`：为`消费者`提供食品来源的方法。
`消费者`：消费经过正当途径采购、处理和运输的食品。 | -| 成功情景 | 因为可以核实食物来源，`消费者`的满意度得到了提高。 | -| 成功标准 | `消费者`在做出购买决定之前可以核实食品的来源。 | -| 失败标准 | `消费者`无法部分或完全核实食品来源。 | -| 前提条件 | 1. `组织 A` 和`组织 B`都自己注册了提供端到端的食品溯源解决方案的区块链软件服务，但要求链中的所有参与者使用单一解决方案才能工作。
2. `组织 A` 和`组织 B` 的两种解决方案都有条款和条件，以便在技术和法律上能够在软件互相集成以及集成`Cactus`。 | -| 备注 | | - - - - - ---- - - - -
- -## 2.7 终端用户钱包身份验证/授权 - -| W3C 用例属性名称 | W3C 用例属性值 | -|-----------------------------|------------------------------| -| 用例标题 | 钱包验证/授权 | -| 用例 | 1. `用户 A` 分别在不同的授权和非授权账本上拥有公私钥形式（PKI）的身份。
2. `用户 A` 希望通过单独的 API 或者用户接口将这些身份上传到 `Cactus`中来管理这些身份。
3. `用户 A` 更倾向于上传身份，并且现在能够通过或使用 `Cactus` 的终端用户应用程序（例如，通过直接发出 API 请求或使用这样做的应用程序）与保存上述身份的钱包进行交互。 | -| 社交类型 | 身份管理 | -| 描述 | 面向终端用户的应用程序可以为终端用户提供多个许可（或无许可）网络无缝连接的体验，终端用户拥有一组用于不同账本上的钱包的不同身份证明。 | -| 参与者 | `用户 A`：其身份通过单个 `Cactus` 部署进行加强的人或实体。 | -| 参与者目标 | `用户 A`：以一种方便的方式来管理一系列不同的身份，同时权衡一个`Cactus`部署必须与所涉及身份的私钥相信任（这是用户有经验的决定）。 | -| 成功情景 | `用户 A` 可以与他们的钱包进行交互，而不必单独访问每个私钥。 | -| 成功标准 | `用户A` 的凭证被安全地存储在 `Cactus` 的密钥串组件中，在那里它们被破坏的可能性最小（注意，当然，被破坏从来都不是不可能的，但以最小的不可能性） | -| 失败标准 | `用户 A` 不能向 `Cactus` 导入身份，原因有很多比如密钥格式不兼容。 | -| 前提条件 | 1. `用户 A` 必须在导入之前在各种分类账上设置身份，并且必须有权访问私钥。 | -| 备注 | | - - - ---- - - - -
- -## 2.8 区块链迁移 - -| W3C 用例属性名称 | W3C 用例属性值 | -| ---------------- | ------------------------------------------------------------ | -| 用例标题 | 区块链迁移 | -| 用例 | 1. `联盟 A` 在源区块链上操作一组服务或用例。
2. `联盟 A` 决定使用另外一个区块链基础设施支持他的用例
3. `联盟 A` 将现有资产迁移到另外一个区块链。 | -| 社交类型 | 资产转移 | -| 描述 | 运营源区块链（例如，Hyperledger Fabric 实例）的一组成员（`联盟 A`）希望将功能迁移到目标区块链（例如，Hyperledger Besu），以扩大其覆盖范围。然而，这种迁移需要大量的资源和技术努力。来自 Hyperledger Cactus的“区块链迁移功能”可以通过连接源区块链和目标区块链并执行迁移任务来提供支持。 | -| 参与者 | 1. 联盟成员组成的`联盟 A`：操作源区块链的一组实体，他们的共同目标是实现向目标区块链的迁移。 | -| 参与者目标 | `联盟 A` 想要在目标区块链上操作他们的用例。服务在迁移后可用。 | -| 成功情景 | 联盟一致同意以去中心化方式迁移。区块链成功迁移并且没有出现问题。 | -| 成功标准 | 资产完成迁移。那些资产的身份历史在目标区块链中完成重构。 | -| 失败标准 | 1. 资产没有迁移。
2. 不能在目标区块链中重构资产历史。 | -| 前提条件 | 1. 所有`联盟 A` 中的成员都想迁移区块链。
2. `联盟 A` 控制着源区块链。
3. `联盟 A` 拥有目标区块链的写权限。
| -| 备注 | 资产的定义是，源区块链产生的数据或者智能合约。
该用例和资产可移植的用例相关（例如，2.1）。
该用例提供了区块链的可移植性，从而降低了成本并促进了区块链的采用。 | - ---- -动机：区块链解决方案对于用例的适用性取决于底层区块链属性。随着区块链技术的快速成熟，特别是私有区块链，其属性可能会发生变化。因此，这就造成了用户期望和解决方案适用性之间的不平衡。因此，一个组织希望能够取代为某项服务提供基础设施的区块链。 - -目前，当一个联盟想要迁移他们的区块链时（例如，源区块链已经过时，加密算法不再安全等），解决方案是使用不同的平台重新实现业务逻辑，需要付出巨大的努力。数据迁移在公链中实现过 [[2](#7-references),[3](#7-references)]，他们最近都在努力为基于区块链的解决方案提供灵活性。在这些工作中，作者提出了公共的、无许可的区块链的简单数据迁移功能，用户可以在他们的服务支持的区块链基础设施上指定需求。 - - -### 2.8.1 区块链数据迁移 -数据迁移相当于捕获源区块链上数据资产（信息，以字节形式）的集合或子集，并构建目标区块链中这些资产的表示。请注意，两个区块链的基础模型不必相同（例如，Hyperledger Fabric 的世界状态模型与以太坊中的帐户模型）。要迁移数据，就要能够从源区块链捕获必要的信息并将其写入目标区块链。还要迁移信息的历史记录（例如，元素的更新就可以认为是信息）。 - - - -### 2.8.2 区块链智能合约迁移 -迁移智能合约的任务包括迁移数据的任务。具体来说，信息应该可以在另一个区块链上访问和写入。此外，目标区块链的虚拟机应支持源区块链的计算复杂性（例如，不能将所有以太坊智能合约迁移到比特币，但反过来是可行的）。 - -自动智能合约迁移为企业区块链系统带来风险，因此解决方案非常重要。 - -### 2.8.3 半自动区块链迁移 - -通过我对功能性和非功能性需求的偏好，Hyperledger Cactus 可以推荐一组合适的区块链作为迁移的目标。首先，我可以实时了解目标区块链的特征，这将影响我的决策。例如，平台可以分析向以太坊写入信息的成本、美元-以太币的汇率、出块的平均时间、事务吞吐量和网络哈希率[[3](#7-references)]。在此基础上，该框架提出了一个迁移方案，其中包括预测成本、完成迁移的预计时间和成功的可能性等指标。由于以太坊没有显示出理想的吞吐量，所以我选择了 Polkadot 的平台。当它产生更高的吞吐量时，我就安全地将我的解决方案从 Fabric 迁移到 Polkadot，而不影响生产中的解决方案。对于公共区块链，此功能更有用。 - - -
- - -# 3. 软件设计 - -## 3.1. 原则 - -### 3.1.1. 广泛的支持 - -连接尽可能多的经济系统，而没有技术限制 - -### 3.1.2. 尽可能的插件化架构 - -身份、DLT、服务发现。最小固化，我们拥抱互操作性而不是孤立和锁定。密切关注社区反馈和 PR 以确定 Hyperledger Cactus 核心代码可以提取为插件的功能。限制限定以便添加未来的使用用例和协议。 - -### 3.1.3. 尽可能避免双花 - -同一时间内相同资产不能存在的两种形式，除非有明确的标识，比如【截止10月30号限定在特定 DLT 组合中；例如：不适用于 Fabric + Bitcoin】。 - -### 3.1.4 特性的包容性 - -每个 DLT 都包含一些和其他 DLT 部分或完全不同过的特性。Hyperledger Cactus 应该设计一种通过 Hyperledger Cactus 和 DLT 交互时使用这些特性的方式。该原则的一个最佳实践示例是 Kubernetes CRD 以及操作员允许社区以可重用方式扩展 Kubernetes 核心 API。 - -### 3.1.5 低影响 - -互操作性不是重定义生态系统而是适应它们。治理、信任模型和工作流依旧保留在每个生态系统中。信任模型和一致性必须是协议握手的强制性部分，这样任何可能的不兼容性都会以透明的方式预先显示出来，并且双方都可以“各走各的”，而不会意外地丢失资产或数据。该灵感来自于传统在线交易支付流程 API，它允许商人在交易结束前指定可接受的保障级别（例如，需要锁定、签名的收据等）。按照相同的逻辑，我们应该允许交易参与者指定他们需要的共识、交易最终性的顺序。共识需求必须支持谓词，例如“我在 Fabric 上，但是会接受 Bitcoin 确认 X 个区块后的交易。”还可以添加要求 KYC（了解您的客户）合规性的内容，以帮助尽可能多地促进采用。 - -### 3.1.6 透明性 - -跨生态交易参与者会意识到该转移带来的本地和全局的影响。所有参与者会在有限拒绝和错误是及时沟通。这种透明性应该像可信的证据一样可见。 - -### 3.1.7 自动化的工作流 - -每个生态系统中的逻辑构成了具有复杂的互操作性的用例。跨生态系统的转移可以在响应前一个转移时自动触发。自动化程序，无论错误恢复或者异常处理，都应该无中断地执行。 - -### 3.1.8 默认最高的安全性 - -支持最少的安全选项，并且严格的限制进入，不允许退出。 - -### 3.1.9 交易协议协商 - -交易的参与者必须有一个握手机制，这样他们可以一致同意执行交易使用的支持的协议。该算法在参与者支持的算法列表中找到交叉点。 - -### 3.1.10 避免任何区块链网络上数字资产总量的变动的可能 - -我们相信增加或减少苏子资产的总量将会减弱区块链的安全性，因为增加和减少资产是复杂的。相反，中间的实体（例如，交换者）可以公用和/或发送传输。 - -### 3.1.11 提供通用操作的抽象 - -我们的公共模块化应该扩展到在区块链上操作和/或发现交易的通用机制。 - -### 3.1.12 集成身份框架（Moonshot） - -不限制身份框架，要允许`Cactus`的用户使用最常用的身份框架并且支持未来通过插件化的架构对扩展身份框架的支持列表。支持`Cactus`的用户实现身份验证、授权和读写证书。 - -原生支持或考虑的身份框架： - -* [Hyperledger Indy (Sovrin)](https://www.hyperledger.org/projects/hyperledger-indy) -* [DIF](https://identity.foundation/) -* [DID](https://www.w3.org/TR/did-core/) - -## 3.2 特性需求 - -### 3.2.1 新协议的集成 - -增加新的协议必须成为插件架构的一部分，以便社区可以提议、开发、测试和发布他们实现的协议。 - -### 3.2.2 代理/防火墙/NAT 能力 - -意思是尽可能通过代理/防火墙/NAT 建立双向通信通道。 - -### 3.2.3 双向通信层 - -尽可能通过代理/防火墙/NAT使用一个区块链不可知的双向通信通道来控制和监控区块链上的交易。 - - * 区块链的 P2P 通信协议不同。最好构建一个模块的方法来发送、接收区块链中值得信任的实体之间的通用交易。 - -### 3.2.4 联盟管理 - -联盟可以由合作和实体组成（人，组织等），他们都希望贡献硬件或者网络资源来操作一个`Cactus`集群（验证者集合，API服务器等）。 - -在最初的成员（一个或多个）集合构建哇按成一个联盟之后，它也要能够增加或移除新的或退出的成员。 - -`Cactus`不规定任何增加或者移除联盟成员的共识算法，而是专注于技术层面使它可以在独立实体的所有权下操作节点集群，而不用增加或移除成员的时候停机。 - -一个新加入联盟的成员不需要参与`Cactus`的所有组件：运行一个验证者节点就可以了，etcd、API 服务器可以保持新成员加入之前的状态。 - -## 3.3 工作策略 - -1. 参与者可以假装只支持他们所提出的协议，从而坚持特定的协议。 -2. 随着规范的成熟，可以对协议进行版本控制。 -3. 最初支持的两个协议应分别满足富士通和埃森哲实现的要求。 - -
- -# 4. 架构 - -## 4.1 集成模式 - -Hyperledger Cactus 有如下多种集成模式。 - -- 注意：在下边的描述中，**Value(V)**的意思是数字资产（例如，钱）。**Data(D)**的意思是非数字资产（例如，所有权证明）。账本1是原账本，账本2是目标账本。 - -| No. | Name | Pattern | Consistency | -| ---- | ------------- | ------- | ------------------------------------------------------------ | -| 1. | 数值转移 | V -> V | 检查是否 V1 = V2
（V1 是账本 1 上的数值，V2 是账本 2 上的数值） | -| 2. | 数值-数据转移 | V -> D | 检查是否数值转移完成后数据也成功转移了 | -| 3. | 数据-数值转移 | D -> V | 检查是否数据转移完成后数值也成功转移了 | -| 4. | 数据转移 | D -> D | 检查是否所有 D1 都复制到了账本2
（D1 是账本 1 上的数据，D2 是账本 2 上的数据） | -| 5. | 数据合并 | D <-> D | 最终是否 D1 = D2
（D1 是账本 1 上的数据，D2 是账本 2 上的数据） | - -## 4.2 系统架构和基本流程 - -Hyperledger Cactus 将通过跨多区块链账本执行账本的操作提供集成服务。操作的执行由 Hyperledger Cactus 的模块控制，该模块将以单个 Hyperledger Cactus 业务逻辑插件的方式提供。Hyperledger Cactus 支持的区块链平台可以通过实现新的 Hyperledger Cactus 账本插件来加入。当用户通过 API 调用 Hyperledger Cactus 框架的时候，业务逻辑插件决定由哪个账本执行操作，它确保发布的集成服务的可靠性符合预期。下边的图片展示了在 Hyperledger Cactus 项目会议上讨论的 Hyperledger Cactus 架构。整体架构如下图。 - - - -每个实体如下： -- **Application user（应用程序用户）**: 提交 API 调用到 “Cactus 路由接口”的实体。 -- **Business Logic Plugin（业务逻辑插件）**: 该实体执行业务逻辑并提供多个区块链连接的集成服务。该实体有 Web 应用程序或区块链上的智能合约组成。该实体是运行 Hyperledger Cactus 应用程序时所必须的一个独立的插件。 -- **Ledger Plugin（账本插件）**: 该实体是每个账本进行通信的业务逻辑插件。该实体由下边的验证器和验证者组成。该实体可通过配置从不同的插件中选择。 -- **Validator（验证器）**: 该实体监控账本操作的交易记录，并且决定就交易记录的结果（成功、失败、超时）。验证器确保带有“验证器密钥”数字签名的结果可以被“验证者”验证。 -- **Verifier（验证者）**: 该实体只接收验证器签名验证通过了的操作结果。注意，“验证器”是“验证者”双向通道的一部分。 -- **Cactus Routing Interface（Cactus 路由接口）**: 该实体是“业务逻辑插件”和“账本插件”的路由服务。该实体也是业务逻辑插件和“应用程序用户”调用 API 的路由服务。 -- **Ledger-n（账本-n）**: DLT 平台（例如：Ethereum，Quorum，Hyperledger Fabric ...） - -执行步骤如下： -- **步骤 1**: “应用程序用户”提交 API 调用到 “Cactus 路由接口”。 -- **步骤 2**: API 调用由 “Cactus 路由接口”在内部将“业务逻辑插件”和业务逻辑初始关联起来。然后，“业务逻辑插件”决定需要的账本操作来完成或者终止业务逻辑。 -- **步骤 3**: “业务逻辑插件”提交 API 调用“账本”上需要的操作，“账本”由“账本插件”包装。每个 API 调用都将由“路由接口”路由到设计好的“账本插件”上。 -- **步骤 4**: “账本插件”通过“Cactus 路由接口”向“业务逻辑插件”发送事件提醒，当它的子组件“验证者”检测到有“账本”的账本操作请求事件时。 -- **步骤 5**: “业务逻辑插件”从“账本插件”接收消息并决定业务逻辑的完成或者继续。当业务逻辑需要继续执行时跳到“步骤 3”，否则终止程序。 - -
- -## 4.3 技术架构 - -### 4.3.1 Monorepo包 - -Hyperledger Cactus 拆分成了一组 npm 包，这些包可以单独或一次全部编译。 - -所有的包都有一个 `cactus-*` 前缀来避免和其他 Hyperledger 项目发布的 npm 命名冲突。例如，如果 Cactus 和 Aries 都在 `@hyperledger` npm 范围下发布了一个名为 `common` 的包，该包的全限定报名就会是（没有前缀时） `@hyperledger/common` ，如果加上前缀就可以解决冲突问题，包名就成了 `@hyperledger/cactus-common` 和 `@hyperledger/aries-common`。在这里 Aries 只是一个示例，我们并不知道他们是否计划发布这样命名的包，但是这并不影响我们的示范。 - -包的命名习惯： -* cmd-* 存放包的可执行文件。 -* sdk-* 存放应用开发者可以直接使用的包， Javascript SDK 除外，它的名字直接是 `sdk`。 -* 所有其他包的命名，比如表明包的主要特性/职责的单个英文单词也是可取的。 - -#### 4.3.1.1 cmd-api-server - -启动 API 服务器的命令行应用程序，它为调用代码提供了统一的基于 REST 的 HTTP API。包含了 Hyperledger Cactus 的核心。此处的代码是固定的，其余的被推送到实现了插件或者定义了它们的接口的其他包。使用 Swagger API 定义，插件在内部加载。 - -> 这个地方的设计是无状态且可以水平扩展。 - -**该包的主要职责：** - -##### 4.3.1.1.1 运行时配置解析和验证 - -核心包的职责是从通用源中解析运行时配置（按优先级排序）： -* 代码中明确指定 (`config.setHttpPort(3000);`) -* 命令行参数 (`--http-port=3000`) -* 操作系统环境变量 (`HTTP_PORT=3000`) -* 静态配置文件 (config.json: `{ "httpPort": 3000 }`) - -使用 Apache 2.0 许可下的 node-convict 库来做配置的解析和验证：https://github.com/mozilla/node-convict - -##### 4.3.1.1.2 配置模式 - API 服务器 - -要想获取最新的配置选项，你可以切换到 Cactus 最新的源码并在装有 NodeJS 10 或更新版本的机器上进入项目根目录来运行： - -```sh -$ date -Mon 18 May 2020 05:09:58 PM PDT - -$ npx ts-node -e "import {ConfigService} from './packages/cactus-cmd-api-server/src/main/typescript/config/config-service'; console.log(ConfigService.getHelpText());" - -按降序的参数的优先顺序：CLI，环境变量，配置文件。输入“help”作为第一个参数打印这些信息同时显示有效的配置。 - -配置参数 -======================== - - plugins: - Description: A collection of plugins to load at runtime. - Default: - Env: PLUGINS - CLI: --plugins - configFile: - Description: The path to a config file that holds the configuration itself which will be parsed and validated. - Default: Mandatory parameter without a default value. - Env: CONFIG_FILE - CLI: --config-file - logLevel: - Description: The level at which loggers should be configured. Supported values include the following: error, warn, info, debug, trace - Default: warn - Env: LOG_LEVEL - CLI: --log-level - cockpitHost: - Description: The host to bind the Cockpit webserver to. Secure default is: 127.0.0.1. Use 0.0.0.0 to bind for any host. - Default: 127.0.0.1 - Env: COCKPIT_HOST - CLI: --cockpit-host - cockpitPort: - Description: The HTTP port to bind the Cockpit webserver to. - Default: 3000 - Env: COCKPIT_PORT - CLI: --cockpit-port - cockpitWwwRoot: - Description: The file-system path pointing to the static files of web application served as the cockpit by the API server. - Default: packages/cactus-cmd-api-server/node_modules/@hyperledger/cactus-cockpit/www/ - Env: COCKPIT_WWW_ROOT - CLI: --cockpit-www-root - apiHost: - Description: The host to bind the API to. Secure default is: 127.0.0.1. Use 0.0.0.0 to bind for any host. - Default: 127.0.0.1 - Env: API_HOST - CLI: --api-host - apiPort: - Description: The HTTP port to bind the API server endpoints to. - Default: 4000 - Env: API_PORT - CLI: --api-port - apiCorsDomainCsv: - Description: The Comma seperated list of domains to allow Cross Origin Resource Sharing from when serving API requests. The wildcard (*) character is supported to allow CORS for any and all domains, however using it is not recommended unless you are developing or demonstrating something with Cactus. - Default: Mandatory parameter without a default value. - Env: API_CORS_DOMAIN_CSV - CLI: --api-cors-domain-csv - publicKey: - Description: Public key of this Cactus node (the API server) - Default: Mandatory parameter without a default value. - Env: PUBLIC_KEY - CLI: --public-key - privateKey: - Description: Private key of this Cactus node (the API server) - Default: Mandatory parameter without a default value. - Env: PRIVATE_KEY - CLI: --private-key - keychainSuffixPrivateKey: - Description: The key under which to store/retrieve the private key from the keychain of this Cactus node (API server)The complete lookup key is constructed from the ${KEYCHAIN_SUFFIX_PRIVATE_KEY} template. - Default: CACTUS_NODE_PRIVATE_KEY - Env: KEYCHAIN_SUFFIX_PRIVATE_KEY - CLI: --keychain-suffix-private-key - keychainSuffixPublicKey: - Description: The key under which to store/retrieve the public key from the keychain of this Cactus node (API server)The complete lookup key is constructed from the ${KEYCHAIN_SUFFIX_PRIVATE_KEY} template. - Default: CACTUS_NODE_PUBLIC_KEY - Env: KEYCHAIN_SUFFIX_PUBLIC_KEY - CLI: --keychain-suffix-public-key - - -``` - -##### 4.3.1.1.4 插件加载/验证 - -NodeJS 的内置木块加载器加载插件，Node 包管理工具（npm）在验证插件，验证时按照字节级别完整的验证所有安装的模块。 - -#### 4.3.1.2 core-api - -包含插件架构和其他很多包共享的系统级组件的接口定义。`core-api` 的目的是成为一个叶子包，意思是说它不依赖其他包，所以所有依赖 `core-api` 的包会更加安全，不必解决循环依赖问题。 - -#### 4.3.1.4 sdk - -`cmd-api-server` 提供的 RESTful HTTP API 的 Javascript SDK（绑定的）。兼容 NodeJS 和 Web 浏览器（HTML 5 DOM + ES6）环境。 - -#### 4.3.1.5 密钥串（keychain） - -负责以加密格式持久存储敏感数据（例如，私钥）。 - -API 层面的更多细节，请查看`插件架构`下的相关章节。 - -#### 4.3.1.7 追溯 - -包含用于追溯、记录和其他 Hyperledger Cactus 包的代码的应用性能管理（APM）的组件。 - -#### 4.3.1.8 审核 - -用于写和读取审核记录的组件必须可以持久保存且不可篡改。后一个属性是审计日志与跟踪/日志消息的区别，跟踪/日志消息的设计是短暂的，用于支持技术问题，而不是与法规/合规/治理相关的问题。 - -#### 4.3.1.9 文档存储 - -为其他包，如`审核`和`追溯`，提供结构化或非结构化的文档存储和分析能力。使用它自己的 API 层通过插件实现不同后端存储服务的适配。默认使用 `Open Distro for ElasticSearch` 作为后台存储： https://aws.amazon.com/blogs/aws/new-open-distro-for-elasticsearch/ - - - -> 该包提供的 API 层保持了简洁和功能的精简，因此通过 `Cactus` 架构不同的底层后端存储可以作为一个选项长久保持。 - -#### 4.3.1.10 相关存储 - -包含负责提供访问兼容标准 SQL 的持久存储的组件。 - -> 该包提供的 API 层保持了简洁和功能的精简，因此通过 `Cactus` 架构不同的底层后端存储可以作为一个选项长久保持。 - -#### 4.3.1.11 不可篡改存储 - -包含的负责提供访问不可篡改存储组件，比如带有只能追加语义的分布式账本，就像区块链网络（如，Hyperledger Fabric）。 - -> 该包提供的 API 层保持了简洁和功能的精简，因此通过 `Cactus` 架构不同的底层后端存储可以作为一个选项长久保持。 - -### 4.3.2 部署图 - -Source file: `./docs/architecture/deployment-diagram.puml` - - - -### 4.3.3 组件图 - - - -### 4.3.4 类图 - -### 4.3.5 时序图——交易 - -TBD - -
- -## 4.4 交易协议说明 - -### 4.4.1 握手机制 - -TBD - -### 4.4.2 交易协议协商 - -交易参与者必须有一个握手机制，一次来来同意执行一个大家都支持的用于执行交易的协议。该算法查找参与者支持的算法列表的交叉点。 - -参与者可以通过假装只支持自己所说的协议的方式坚持使用特定协议。随着规范的成熟，可以对协议进行版本控制。作为插件架构，必须添加新协议，允许社区提议、开发、测试和发布他们自己的实现。最初支持的两个协议应分别满足 Fujitsu（富士通）和 Accenture（埃森哲）的要求。尽可能通过代理/防火墙/NAT建立双向通信信道。 - -
- -## 4.5 插件架构 - -因为我们目的是集成，所以 `Cactus` 要能够灵活地支持多种的账本，尽管目前还没有实现。 - -> 插件是一个自包容的代码片段，实现了 `Cactus` 中为特定功能预定义的接口，比如交易执行。 - -插件是核心组件顶层的抽象，支持 `Cactus` 操作者根据意愿切换不同的实现。 - -> 向后兼容性很重要，但插件的版本控制仍然遵循语义版本控制约定，这意味着主要升级可能会有破坏性的更改。 - -插件使用 ES6 模组（源码）实现，可以在运行环境中从持久化数据存储中加载。核心包负责验证代码签名来保证源码的完整性。 - -插件架构涵盖的所有方面的一个总体主题是，每个方面都应该有一个傻瓜式实现，以允许在单个消费级机器上部署，而不是昂贵的硬件和专业知识。 - -> 理想情况下，一个完全可测试/可操作（但是还没有成为产品）的 `Cactus` 部署应该可以通过一个简单的命令（比如一个 npm 脚本）在开发者的笔记本上运行。 - ---- - - - ---- - -### 4.5.1 账本连接器插件 - -成功的定义是： -1.在 `Cactus` 中添加对未来发明的账本的支持不需要修改`核心`代码，而是可以通过简单地添加相应的连接器插件处理新账本来实现。 -2. 使用 REST API 和利用特性检查的客户端应用程序可以保持 100% 的功能，而不管 `Cactus` 中部署的连接器插件的数量和性质如何。例如：一个通用的汇款应用程序不必对其支持的账本进行硬编码，因为统一的 REST API 接口（由账本连接器插件提供）保证了支持的功能可以运行。 - -由于不同账本的功能可能非常不同，插件接口内置了功能检查，以支持调用方/客户端应用程序**在运行时以编程方式确定**给定账本上是否支持某个功能。 - -```typescript -export interface LedgerConnector { - // method to verify a signature coming from a given ledger that this connector is responsible for connecting to. - verifySignature(message, signature): Promise; - - // used to call methods on smart contracts or to move assets between wallets - transact(transactions: Transaction[]); - - getPermissionScheme(): Promise; - - getTransactionFinality(): Promise; - - addForeignValidator(): Promise; -} - -export enum TransactionFinality { - GUARANTEED = "GUARANTEED", - NOT_GUARANTEED = "NOT_GUARANTEED -} - -export enum PermissionScheme { - PERMISSIONED = "PERMISSIONED", - PERMISSIONLESS = "PERMISSIONLESS" -} - -``` - -### 4.5.2 身份联盟插件 - -身份联盟插件在 API 服务器内部运行并且需要实现通用 PassportJS 策略的接口：https://github.com/jaredhanson/passport-strategy#implement-authentication - -```typescript -abstract class IdentityFederationPlugin { - constructor(options: any): IdentityFederationPlugin; - abstract authenticate(req: ExpressRequest, options: any); - abstract success(user, info); - abstract fail(challenge, status); - abstract redirect(url, status); - abstract pass(); - abstract error(err); -} -``` - -#### 4.5.1.1 X.509证书插件 - -X.509证书插件允许客户端提供证书，而不是使用身份验证令牌操作，从而简化了客户端身份验证。这在技术上允许调用客户端通过 REST API 获取验证器节点的身份，而不必访问验证器节点的签名私钥。 - -PassportJS 已经有为客户端证书验证而写的插件了，但是我们在此插件上更进了一步，提供了在运行时从验证器节点自己获取 CA 证书的选项。 - -### 4.5.3 Key/Value 存储插件 - -Key/Value 存储插件支持更高级别的包来存储和检索 `Cactus` 集群的配置元数据，比如 -* 谁是活跃验证器和网络中可访问验证器的主机名？ -* 哪个公钥属于哪个验证器节点？ -* 哪些交易已经预定了、哪些已经开始了，哪些结束了？ - -```typescript -interface KeyValueStoragePlugin { - async get(key: string): Promise; - async set(key: string, value: T): Promise; - async delete(key: string): Promise; -} -``` - -### 4.5.4 服务端密钥串插件 - -密钥串插件在 API 层面上和 Key/Value *存储*插件插件差不多，但是在幕后，它们当然可以通过利用专门为存储和管理机密数据而构建的存储后端来加密静态存储的数据。 - -可能的存储后端还包括自己管理的软件 [1] 和云原生服务 [2][3][4]。密钥串插件（从大方面说还有插件架构）的目的是使 `Cactus` 可部署在有不同后端服务的环境中，比如在部署的数据中心或者出售机密管理服务/API的云服务商。这应该是傻瓜式的，同样还有将机密数据保存在内存和解密也一样（严格来说只是部署方面）。后者将减少新用户进入的障碍，并可能成为像贡献者一样的人。 - -直接支持 HSM（Hardware Security Modules，硬件安全模块）也是密钥串插件需要支持的，但是这个优先级比较低，因为考虑到所有严谨的带有机密数据管理的存储后端都将内置对处理 HSM 透明的支持。 - -根据设计，密钥串插件只能由具有活动 `Cactus` 会话的经过身份验证的用户使用。用户的机密信息通过密钥串插件内部实现的命名空间在密钥串上相互隔离（例如，用户不能查询其他用户的命名空间）。 - -```typescript -interface KeychainPlugin extends KeyValueStoragePlugin { -} -``` - -[1] https://www.vaultproject.io/ -[2] https://aws.amazon.com/secrets-manager/ -[3] https://aws.amazon.com/kms/ -[4] https://azure.microsoft.com/en-us/services/key-vault/ - -
- -# 5. 身份、认证、授权 - -`Cactus` 的目标是提供管理身份拥有者身份的统一 API。开发者在他们的应用程序中使用 `Cactus` REST API 可以支持以下其中一个或者两个需求： -1. 关注访问控制和高效业务处理（通常在企业中）的应用程序。 -2. 关注个人隐私（通常是基于客户的应用）的应用程序。 - -下边的章节概括了 `Cactus` 中实现上述情况的高级特性。 - -终端用户（通过用户接口）可以发出 API 请求来： -* **在** `Cactus` 中注册一个用户名+密码的账户。 -* 将他们的 `Cactus` 账户关联到他们的钱包并且使用注册过的钱包执行交易（就像前边说的可以通过本地或者远程进行交易签名）。 - -## 5.1 交易签名模式、键所有权 - -使用 `Cactus` 的应用开发者可以选择支持用户在他们本地的代理设备上本地签名他们的交易而不向 `Cactus` 暴露他们的私钥，或者远程使用 `Cactus` 服务端存储的私钥静态加密，通过授权他们的 `Cactus` 账户进行解密。每种方式都有他们的利弊，设计时需要仔细考虑。 - -### 5.1.1 客户端交易签名 - -通常更适用于用户有更高的个人隐私需求的基于消费者的应用程序。 - -**优势** -* 当 `Cactus` 部署被破坏时，密钥不被破坏 -* `Cactus` 部署的操作员不对密钥的安全负责（和上面一样） -* 降低了服务端的复杂度（不用中心化管理密钥） - -**劣势** -* 与服务器端交易签名相比，用户体验是次优的 -* 用户会永远失去访问权如果他们丢失了密钥（在多数企业级/专业的用例中是不可接受的） - ---- - - - ---- - -### 5.1.2 服务端交易签名 - -通常适用于企业级应用，由于服从、治理、内部或外部政策约束终端用户更愿意降低对隐私的期望。 - -**优势** -* 免去了用户管理密钥的负担（用户体验更好） - * 改进了法规遵从性和治理 - -**劣势** -* 服务端被破坏会泄露存储在密钥串上的被加密的密钥。 - ---- - - - ---- - -## 5.2 Open ID 链接提供者、身份提供者 - -`Cactus` 可以通过*第三方身份提供者*或自己作为*身份提供者*验证用户。一切都遵循公认的 Open ID Connect 行业标准，以最大限度地提高信息安全性并降低数据泄露的可能性。 - -## 5.3 Web应用的服务端密钥串 - -传统的 web 或移动端应用程序和区块链应用程序（web 2.0 和 3.0，如果你愿意的话）认证协议之间存在着差距，因为区块链网络依赖于属于公钥基础设施（PKI）的私钥来认证用户，而传统的 Web 或移动端应用程序主要依赖于中央集权存储的散列后的密码，以及在成功验证身份（例如，使用密码成功登录）后颁发的临时令牌。传统（Web 2.0）应用程序（遵循安全最佳实践）使用服务器端会话（Web）或操作系统（iOS、Android等）提供的安全密钥串。目前企业应用开发行业的行业标准和最先进的认证协议是 Open ID Connect（OIDC）。 - -为了成功缩小这两个世界之间的差距，`Cactus` 配备了一个 OIDC 身份提供者和一个服务器端密钥串，终端用户应用程序可以利用该密钥串对 Hyperledger Cactus 进行一次身份验证，并通过该 Hyperledger Cactus 身份管理其他区块链上的身份。此功能对于没有安全脱机存储 API（HTML localStorage不安全）的 Web 应用程序非常重要。 - -示例：用户可以注册一个 Hyperledger Cactus 帐户，从其 Fabric 或 Ethereum 钱包中导入私钥，然后通过仅对 `Cactus` 进行一次身份验证来访问所有这些身份，这将产生一个包含 JSON Web Token（JWT）的服务器端会话（HTTP cookie） 。 - -> 原生移动应用程序可能不需要使用服务器端密钥串，因为它们通常配备操作系统提供的密钥串（Android、iOS就是这样）。 - - - -在 Web 2.0 应用程序中，流行的身份验证/授权解决方案是 Open ID Connect，它基于从密码派生的密码和令牌进行身份验证。与区块链网络交互的 Web 3.0 应用程序（分散应用程序或 *DApps*）依赖私钥而不是密码。 - -
- -# 6. 术语 - -**应用用户**：向 Hyperledger Cactus 应用或智能合约请求 API 调用的用户。API 调用触发向远程账本发送交易。 - -**Hyperledger Cactus Web 应用或区块链上的智能合约**：执行商业逻辑并提供多个区块链集成服务的实体。 - -**Tx 验证者**： 验证从安全双向通道发送来的交易数据的签名的实体。已验证的交易会被 Hyperledger Cactus Web 应用处理或者由智能合约执行相应的业务逻辑。 - -**Tx 提交者**：提交远程交易到其中一个账本的 API 服务器的实体。 - -**API 服务器**：Hyperledger Cactus 的一个模块，提供了统一处理/控制在它后面的区块链账本的接口。 - -**验证者**：Hyperledger Cactus 的一个模块，验证发送到区块链应用的交易的有效性。 - -**锁定资产**：对区块链账本管理的资产的操作，即禁止对目标资产的操作。目标根据资产类型可以是全部或者部分。 - -**终止**：Hyperledger Cactus 的一个状态，表明账本操作失败，Hyperleder Cactus 将执行恢复操作。 - -**集成账本操作**：一系列区块链账本的操作，这些操作由 Hyperledger Cactus 触发。当 "终止" 发生时 Hyperledger Cactus 有责任执行 "恢复操作"。 - -**恢复操作**：单个或者多个账本操作，由 Hyperledger Cactus 执行在集成操作前来恢复集成服务的状态。 - -**终端用户**：与 Hyperledger Cactus 或者其他账本相关系统交互的人（个人或者公司职员），他们可以完成某些目标，或者完成发送、接收、交换钱或者数据这样的任务。 - -**商业组织**：有一个或多个人组成的盈利或非盈利组织，来实现经济收益或者特定（非盈利组织）目标。简单来说，本文中*商业组织*可以简写为*组织*。 - -**身份所有者**：对一个或多个身份拥有控制权的个人或组织。例如，一个拥有两个独立邮箱账户的人意味着这个人是两个独立身份（邮箱账本）的身份所有者。拥有加密货币钱包（钱包私钥）也是一个身份所有者。 - -**身份密码**：一个只有身份拥有者知道的私钥或者密码（除非被窃取）。 - -**证书**：可以是 IT 应用中`用户身份认证`证书或身份的证明，也可以是交易场景中的其他证书，比如证明一个人拥有学士或者博士学位。 - -**账本/网络/链**：同义词，本文中使用他们表示相同的内容。 - -**OIDC**：Open ID 链接身份验证协议。 - -**PKI**：Public Key Infrastructure，公钥基础设施 - -**MFA**: Multi Factor Authentication，多因子验证。 - -
- -# 7. References 参考文献 - -1: [Heterogeneous System Architecture](https://en.wikipedia.org/wiki/Heterogeneous_System_Architecture) - Wikipedia, Retrieved at: 11th of December 2019 - -2: E Scheid and Burkhard Rodrigues, B Stiller. 2019. Toward a policy-based blockchain agnostic framework. 16th IFIP/IEEE International Symposium on Integrated Network Management (IM 2019) (2019) - -3: Philipp Frauenthaler, Michael Borkowski, and Stefan Schulte. 2019. A Framework for Blockchain Interoperability and Runtime Selection.