この記事で学べること

Cordaの設計図であるCDLの概要と、Mermaidを用いた CDLの描画方法

目次

• はじめに
• CDLとは・・？
• The Smart Contract view
• The Ledger Evolution view
• The Business Process Modelling Notation (BPMN) views
• コードによる作図✖️CDL
• 早速記述してみる！
• その前に、そもそもMermaidとは・・？
• 最終的なゴール
• まずは、クラス図をベースに作ってみる。
• 作成結果
• 良い点
• 悪い点
• 次に、ステートマシン図をベースに作ってみる。
• 作成結果
• 良い点
• 悪い点
• 総合評価
• 項目比較
• まとめ
• おわりに
• テンプレート配布

はじめに

SBI R3 Japanビジネス推進部の金子です。いきなりですが、皆様はシステム設計図はどのように作図しておりますか？MiroやFigma、draw.ioのようなデザインツールを使用する場合もありますが、最近では「コード（Markdown）で作図しています」という方も増えてきているのではないでしょうか。コードを用いた作図記法には、plantUMLやMermaidが有名です。ChatGPTで「業務要件からクラス図を作って」とお願いしてみたり、他の作業者が変更を加えてアップデートしやすくしたり等々、あえてコードで作図することによるメリットが高まってきているのでは？と感じています。特にリソースと同じ容量でアップデートできる点が嬉しいです。特にMermaidに関しては、GithubやQiita、Zenn、Notion、VS Code、InteliJなどの最近のよく使われるサービスでも使える場面が増えてきているので、汎用性が非常に高いです。

CDLとは・・？

一方、Cordaアプリケーションを設計する際の作図方法として、Cordapp Design Language(CDL)というものがあり、Cordappの根幹を示す重要な設計図になっています。

Cordappを設計する場合、複数のノードによる相互作用やスマートコントラクトの特性、プライバシーなどを考慮することが必要で、UML言語などの標準アーキテクチャ仕様では表現できないことが多いです。そして、これらの仕様を明確に示すため、「Cordappを設計するためのモデリング言語（CDL）」が生み出されました。（CDLはR3社によって標準化されています。）

また、Corda（もしくはブロックチェーン技術全般）では、技術的な特性がビジネスメリットに直接影響するため、エンジニアだけが仕様を知っている状態は好ましくありません。そこで、CDLを用いれば非エンジニア（ビジネスアナリストやテスターやPM等）でも、アプリケーションの根幹設計についてチームで合意を取りながら開発を進めることが可能です。

CDLはアップデートが繰り返される中でいくつかの図が統合されてきており、現在は３つの図が主要なCDLとして使われています。CDLはUML図では捉えきれない要素を示すための拡張言語のような立ち位置であることをイメージしていただければと思います。ここでは、３つの図について簡単に説明します。

The Smart Contract view

こちらの図は、UML図でいう「クラス図・ステートマシン図」に近く、その名の通りスマートコントラクトの設計を表した図になっています。もう少し具体的に言うと、Stateの設計をベースに細かな各要素の制約（色付きの枠）が明確に示されます。（State単体の制約、署名者の制約、Contract・Command/Flowの制約など）

The Ledger Evolution view

こちらの図も、UMLにおける「クラス図・ステートマシン図」に近い図ですが、１つ目のState設計とは違い、TransactionによるStateの遷移に着目した図になっています。四角の枠がトランザクションを表しており、中の緑枠がこのStateが取りうる遷移内容（つまりcontract/command）を示しています。ちなみに、Aliceと書かれている箇所は、Tx作成に必要な署名者を示しています。

また、プライバシーデータが不必要に誰かに見られないように、プライバシーの共有範囲が明確に示せることも特徴です。（この図では、途中から取引に参加したChalieがどこまでデータをさかのぼれるかを示しています。）

The Business Process Modelling Notation (BPMN) views

こちらの図は、UMLにおける「アクティビティ図」に近い図で、ノード間でのFlowを通じたビジネスプロセスを示しています。こちらは比較的標準的な書き方になっていますが、Cordaロゴがついている箇所では、台帳に書き込まれる処理が行われるなど、細かな違いがあります。

💡

CDLに興味のある方向けに、詳細な記事をご紹介しておきます。↓

CorDapp Design Language (CDL) overview

CorDapp Design Language (CDL) is a set of diagrammatic views you can use to concisely and accurately guide the design of your CorDapp. Using CDL in the design phase of your CorDapp allows you to: Represent and reason about core aspects of the Corda design including: Ledger data, shared logic, permissioning, and privacy. Reason about more complex CorDapp designs through abstraction from the code and standardisation. Produce complete, well thought-out CorDapp designs.

docs.r3.com

※以下２つは古い記事のため、Tha Smart Contract Viewについては、前身であるState Machine view (Ledger Layer)として解説されています。

Importance of Using Corda Design Language for CorDapps

Looking for a CorDapp that can be effortlessly integrated into your corporate workflow and help enhance your business efficiency and…

medium.com

How to Design a CorDapp and Analyze Privacy Leaks Using CDL Views

Using R3's CDL Views (CorDapp Design Language Views), which is a template of shapes (like the ones that you get in Visio or Lucidchart)

blog.b9lab.com

コードによる作図✖️CDL

Mermaidについて話を戻しますと、UMLで定義された設計図やシステム構成図などはもちろんMermaidでの範疇ですが、CDLでは、UMLで表現できない箇所を示すことが意図されている図のため、どこまでMermaidで表現できるかについては、検証が必要になります。

さて。ここで、天啓が降りてきました。

ということで、実際にCDLをMermaidで作ってみたいと思います。ちなみに当社では、リソース管理にNotionを使うことが多く、Mermaidによる作図もNotion上で可能となれば、執筆速度・バージョン管理・共有の面で作業効率も上がりそうな気がしています。

早速記述してみる！

その前に、そもそもMermaidとは・・？

Mermaidは、グラフ記述言語の1つであり、グラフや図を簡単に作成するためのツールやライブラリを指します。特にウェブベースの文書やプレゼンテーションで使用するために設計された言語で、テキストベースでグラフを記述できるため、コードとして文書に組み込むことができます。(by chatGPT)

上記の通り、MarkdownやHTMLなどのテキストベースの文書フォーマットを用いるため汎用性が高いのが特徴です。

ちなみにUML図の作成が主な用途ですが、UMLで定義されている以外の図もいくつかサポートしており、例えば以下の図をサポートしています。

• パイチャート：全体に対する各部分の割合を視覚化するための図
• ユーザージャーニーマップ：ユーザーの経験を視覚化するための図（PdMには嬉しい）

最終的なゴール

今回は、以下のR3社のCDLサンプルにどれだけ近い図を作れるかを試してみたいと思います。

そもそもCDLは、UMLで言うところのクラス図とステートマシン図を複合したような性質を持っていることから、UMLの定義された各図の要件を満たすように作られているMermaidでは、ある程度の妥協やうまく表現する工夫が必要になります。

まずは、クラス図をベースに作ってみる。

公式Docを参考に作成を進めました。

Class diagrams | Mermaid

Create diagrams and visualizations using text and code.

mermaid.js.org

作成結果

良い点

• 矢印・ラベルのカスタマイズ性が高い
• MC（個数制約。矢印の端の数字で示す）が書きやすい
• クラス図ベースのため矢印の種類が豊富
• 改行が作図内容と直結しており視認性が高い

悪い点

• クラス図内の３つ目のブロック（メンバー）が使えない
• メソッドが含まれることが想定されており、()を付与すると自動で３つ目のブロックに含まれる仕様になっている。
• CDLでは代わりにPerticipantsを表現したいが、仮に()を付与するとメソッドではないため混乱が生じる（対策として、２つ目のブロックにアンダーラインを文字列として追加することにより３つ目のブロックを擬似的に表現）
• 出発点（黒点）や終着点（二重点）の表現ができない
• 現状、styleのカスタマイズが難しい（随時対応予定とのこと。）
• （クラス図・ステートマシン図共通）ブロックを連結する形で表現できない。（Status制約が見にくくなる）
• （クラス図・ステートマシン図共通）矢印に対してコメントブロックを追加することができない。（対策として、中間に図を作成することで矢印のコメントブロックとして表現）

次に、ステートマシン図をベースに作ってみる。

こちらも同様に公式Docを参考に作成を進めました。

State diagrams | Mermaid

Create diagrams and visualizations using text and code.

mermaid.js.org

作成結果

良い点

• styleCSSがカスタム可能
• 出発点（黒点）や終着点（二重点）の表現ができる

悪い点

• ステートマシン図は改行を多用する仕様ではなく、改行では<br>を用いる必要があり、コードの可読性が悪くなる
• （クラス図・ステートマシン図共通）ブロックを連結する形で表現できない。（Status制約が見にくくなる）
• （クラス図・ステートマシン図共通）矢印に対してコメントブロックを追加することができない。（対策として、中間に図を作成することで矢印のコメントブロックとして表現）

総合評価

項目比較

※1 ブロックを連結できないため

※2 矢印に対するコメントブロックが挿入できないため

※3 現状、Mermaid単体でのstyle適応ができないため

※4 改行が使えず、<br>を多用するため

まとめ

Mermaidのコミュニティは活発なため今後さらにアップデートが進むと思いますが、執筆時点でのCDLの書きやすさでは、style適応が柔軟なステートマシン図ベースで作図したCDLが使いやすそうです。ただし、propertiesの項目が増えるとコードの可読性が非常に悪くなる点に注意が必要です。

おわりに

余談ですが、AWSを用いたシステム構成図についても作図される方は多いと思います。CDLとまでは行かずともUML標準の設計図やシステム構成図をMermaidで描けるようになれば、チームでの業務効率が高まると思いますので、是非取り組んでみてはいかがでしょうか。そして使い慣れてきた時には、是非CDLも作図してみると、Cordapp開発がより効率的に進んでいくかもしれません。

テキストから図が生成できるMermaidでAWS構成図をつくる - Qiita

はじめにMermaid記法で記述したテキストからダイアグラムの図が生成できるMermaidでAWS構成図をつくる方法を紹介します。また、MermaidはGithubやQiitaなどのWebサービ…

qiita.com

テンプレート配布

今回作成したコードはそのままテンプレートとして使えるようになっているため、CDLをMermaidで描いてみたい先進的なCordaエンジニアがおりましたらご活用ください。

「とりあえずはデザインツールでCDLを作ってみたい」という方は、R3社のCDLテンプレートも配布されてますので、ご参考ください。