From 1f75a30b64dd7a7a4f44c49ef844d2273f123252 Mon Sep 17 00:00:00 2001 From: Jennifer Bell Date: Tue, 7 Jan 2025 16:01:38 -0500 Subject: [PATCH] docs(copm): Add sequence diagrams for COPM primitives Primary change: adds mermaid sequence diagrams for how COPM primitives are used in asset transfer, asset exchange, and data sharing to copm-core README Secondary change: adds TOC and reformats raw urls to links Signed-off-by: Jennifer Bell --- packages/cacti-copm-core/README.md | 167 ++++++++++++++++++++++++++++- 1 file changed, 162 insertions(+), 5 deletions(-) diff --git a/packages/cacti-copm-core/README.md b/packages/cacti-copm-core/README.md index c01c57fe20..1a46b4fe90 100644 --- a/packages/cacti-copm-core/README.md +++ b/packages/cacti-copm-core/README.md @@ -1,16 +1,31 @@ -# @hyperledger-cacti/cacti-copm-core + +- [Overview](#overview) +- [Usage](#usage) + - [Installation](#installation) + - [Data Sharing](#data-sharing) + - [COPM Command](#copm-command) + - [Figure: Data Sharing with getVerifiedState](#figure-data-sharing-with-getverifiedstate) + - [Asset Transfer](#asset-transfer) + - [COPM Commands](#copm-commands) + - [Figure: Asset Transfer Pledge and ClaimPledge](#figure-asset-transfer-pledge-and-claimpledge) + - [Asset Exchange](#asset-exchange) + - [COPM Commands](#copm-commands-1) + - [Figure: Asset Exchange with Lock and ClaimLock](#figure-asset-exchange-with-lock-and-claimlock) +- [Development](#development) + +# Overview This package defines the common types, interfaces, and endpoints for the COPM module to be used by Digital Ledger-specific implementations. These endpoints require specific chaincode and weaver relays to be deployed on the network. -Please see https://hyperledger-cacti.github.io/cacti/weaver/introduction/. +Please refer to [the Weaver documentation](https://hyperledger-cacti.github.io/cacti/weaver/introduction/). -Endpoint documentation: -https://jenniferlianne.github.io/cacti/references/openapi/cacti-copm-core_openapi/ # Usage +For a detailed command specification, please refer to the [OpenAPI Endpoint Documentation](https://hyperledger-cacti.github.io/cacti/references/openapi/cacti-copm-core_openapi/) + ## Installation Yarn: @@ -18,10 +33,152 @@ Yarn: yarn add --exact @hyperledger-cacti/cacti-copm-core +## Data Sharing + - ability to read data on another network + - the other network must first give you permission + +### COPM Command + - getVerifiedState + +### Figure: Data Sharing with getVerifiedState + +```mermaid +sequenceDiagram + participant Alice + participant COPM gRPC A + participant Ledger A + participant Relay A + participant Relay B + participant Ledger B as Ledger B + Alice->>COPM gRPC A: getVerifiedState for State X on Ledger B + activate COPM gRPC A + COPM gRPC A->>Relay A: Read State X on Ledger B + activate Relay A + Relay A->>Relay B: Read State X + activate Relay B + Relay B->>Ledger B: Read State X + activate Ledger B + Ledger B->>Ledger B: Check permissions + Ledger B->>Ledger B: Read State X + Ledger B->>Relay B: Return signed State X + deactivate Ledger B + Relay B->>Relay A: Return signed State X + deactivate Relay B + Relay A->>COPM gRPC A: Return signed State X + deactivate Relay A + COPM gRPC A->>Ledger A: Verify signature + activate Ledger A + Ledger A->>Ledger A: Verify signature + Ledger A->>COPM gRPC A: Signature Verified + deactivate Ledger A + COPM gRPC A->>Alice: Return State X + deactivate COPM gRPC A +``` + +## Asset Transfer + + - Asset changes networks + - Asset burnt on Ledger A, minted on Ledger B + - Introduces 2 ledger data types: + - Pledge + - A record created on Ledger A when an asset is burnt + - Contains details about the asset, who it is promised to + - Claim + - A record created on Ledger B when the pledged asset is minted +### COPM Commands + - Pledge + - ClaimPledge + +### Figure: Asset Transfer Pledge and ClaimPledge + + +```mermaid +sequenceDiagram + actor Alice + actor Bob + participant System A + participant Asset + participant System B + note right of System B:System: Ledger,
Relay, COPM gRPC + Alice->>Bob: Would you like my Asset? + Bob->>Alice: Yes, please. + Alice->>System A: Pledge Asset + activate System A + System A->>System A: Create Pledge + destroy Asset + System A-xAsset: Burn + deactivate System A + Alice->>Bob: You can claim it now! + Bob->>System B: Claim Pledge + activate System B + rect rgb(191, 223, 255) + System B->>System A: Read Pledge on System A + activate System A + note right of System B: A cross-network
'Data Sharing' flow + System A->>System A: Read Pledge + System A->>System B: Return signed pledge + deactivate System A + end + System B->>System B: Create Claim + create participant PB as Asset + System B->>PB: Mint + deactivate System B +``` + +## Asset Exchange + + - Assets stay where they are + - Two parties swap asset ownership of two assets + - Assets can be on different networks + - Uses HTLC (Hash Time Lock Contract) + - Both parties have visibility of both assets/networks + - No inter-network communication needed + - no relays + +### COPM Commands + - Lock + - ClaimLock + +### Figure: Asset Exchange with Lock and ClaimLock + +```mermaid +sequenceDiagram + actor Alice + actor Bob + participant Token System + participant Bond System + note right of Bond System: System: Ledger and COPM gRPC + Alice->>Bob: Would you like to trade my Tokens for your Bond? + Bob->>Alice: Yes, please. + Alice->>Token System: Lock Tokens + activate Token System + Token System->>Token System: Lock Tokens + deactivate Token System + Bob->>Bond System: Lock Bond + activate Bond System + Bond System->>Bond System: Lock Bond + deactivate Bond System + Alice->>Bob: I've locked my Tokens, the secret is X. + Bob-->>Token System: Sees Tokens are Locked + Bob->>Alice: I've locked my Bond, the secret is Y. + Alice-->>Bond System: Sees Bond is Locked + Alice->>Bond System: Claim Lock for Bond with secret Y + activate Bond System + Bond System->>Bond System: Verify Lock + Bond System->>Bond System: Change Bond owner to Alice + deactivate Bond System + Bob->>Token System: Claim Lock for Tokens with secret X + activate Token System + Token System->>Token System: Verify Lock + Token System->>Token System: Change Token owner to Bob + deactivate Token System +``` + + # Development When implementing a new distributed ledger, the following interfaces must be implemented: - DLTransactionContext: Implements running a transaction on the local network - DLRemoteTransactionContext: Uses the weaver relays to run a transaction on another network -- DLTransactionContextFactory: Factory to return either local or remote context for the specific DLT. \ No newline at end of file +- DLTransactionContextFactory: Factory to return either local or remote context for the specific DLT.