- Go back to TOP(インデックスページへ)
- Context
- Design Process
- Development Process Recommendations
- Testing Recommendations
- Managing Project Keys and Deployments
Context
スマートコントラクトは、Flowブロックチェーンの多くの重要な部分、およびブロックチェーンにデプロイされるあらゆるプロジェクトのセキュリティの基盤となるものです。
スマートコントラクトは、あらゆるプロジェクトにおいて最も目に見える技術的な要素でもあります。それは、ユーザーがデータ照会を行ったり、他のスマートコントラクトと相互に作用するスマートコントラクトを構築したり、学習教材や将来のプロジェクトのテンプレートとして使用したりするためだからです。さらに、デプロイされるとそのスマートコントラクトはブロックチェーン上で公開されるコードとなり、GitHubのリポジトリにもよく公開されます。
それゆえ、これらのプロジェクトを設計、製造、テスト、ドキュメント化、運営を行うプロセスは、スマートコントラクトがエコシステムにおいて持つ極めて重要さを反映する必要があります。
すべてのソフトウェアプロジェクトは、製品/機能の提供に費やす労力と、ソフトウェア開発ライフサイクルにおけるその他の多くの要求（テスト、技術的負債、自動化、リファクタリング、ドキュメントなど）とのバランスを取る必要があります。Web3の構築においても、同様のトレードオフに直面しますが、ほとんどのソフトウェアに典型的なものよりも、リスクと結果が大きい環境です。スマートコントラクトの管理が不十分であったり、テストが行われなかったりすると、見落とされ、脆弱性が悪用されることにより、重大な金銭的損失が発生する可能性があります。私たちは、開発者がこれらのベストプラクティスを採用し、これらのリスクを軽減することを強くお勧めします。
そうすれば、より優れたスマートコントラクトを構築でき、潜在的なバグを回避でき、ユーザーをサポートでき、優れたソフトウェア設計のモデルとなり成功する可能性が高まり、例えばそのプロジェクトがサードパーティとして採用されることになるでしょう。さらに、優れたソフトウェア設計と管理基準を採用するプロジェクトが増えれば、この行動が標準化され、エコシステム内の他のプロジェクトにも同じことを促すことで、より健全で活気のあるコミュニティが生まれることになります。
適切なレベルのテストを確実に実施することで、脅威を事前にモデル化し、それに対抗する設計を施した、より優れたスマートコントラクトが実現することになります。DApp開発者による適切なレベルのスタンダード（FungibleToken、NFT StoreFrontなど）を採用することで、エコシステム内のすべてのネットワーク効果が拡大します。あるDAppのNFTは、新たな統合なしでオンチェーンのEventsを通じて他のDAppで利用されることができます。 貴方の協力と参加により、私たちはFlowエコシステム全体にわたって、健全で活気のあるネットワーク効果をさらに加速させることができます！
これらの提案の中には、やや不要と思われるものもあるかもしれませんが、一つのプロジェクトがそのスマートコントラクトを最善に管理するために何が出来るかを示すことは重要です。そうすれば、他のプロジェクトも追随するかもしれません。
また、標準的なソフトウェア設計のベストプラクティスも適用されることが前提となっています。実際、これらの提案の多くは、より一般的なソフトウェア設計のベストプラクティスですが、他にも前提とされているものの、ここでは含まれていないものがあるかもしれません。
Implementing These Practices
この文書は、プロジェクトが従うべきベストプラクティスの概要を主に提供するものです。 他のベストプラクティスと同様に、チームは自分たちや自分たちの作業プロセスに適用できるものを選択することになりますが、チームには、自分たちにとって最低限受け入れ可能な基準を明示的に定義し、それらが確実に遵守されるためのメカニズムを併せて定義することをお勧めします。
また、一部のチームでは、これと同様の目標を達成するための独自の開発標準を定めている場合もあります。これらの推奨事項は成功への唯一の道筋を示すものではありません。チームがこれらの一部に同意せず、独自のやり方を望む場合は、そのように進めていただいて結構です。この文書は、プロジェクトをどのように管理したいのかわからないチームに対して、一般的な提案をいくつか示しているだけです。
Design Process
スマートコントラクトは通常、沢山の価値を管理しており、多くのユーザーをかかえ、さまざまな理由によりそのアップグレードは困難です。そのためスマートコントラクトの設計プロセスを明確な定義を、大半のコードが書かれる前に行うことが重要であり、それにより、開発チームは成功の為に準備を行うことができます。
以下にプロジェクトはその基盤を構成するかについて、以下がいくつかの推奨事項です。
Projects should ensure that there is strong technical leadership for their smart contracts
DAppの開発には、スマートコントラクトの役割とどのようにスマートコントラクト間を統合するかについてのはっきりしたビジョンが必要です。セキュリティ上の脆弱性が、スマートコントラクトのコード（およびシステム内の他の場所）に直接存在するバグから生じる可能性もあります。非同期な相互作用ベクトルが悪用されると、スマートコントラクトに対するDOS攻撃など悪質な不正行為が発生し、開発者にとって爆発的なガス代が発生したり、その他の問題が発生する可能性があります。
プロジェクトを主導し、メインネットにデプロイするエンジニアには、ソフトウェアとセキュリティエンジニアリングの基本を理解し、Cadenceのスキル開発を徹底的に行うことを推奨します。Cadenceを学習するためのより詳細なリソースは、こちらから入手できます。
技術リーダーは、Cadenceをよく理解し、以前にCadenceスマートコントラクトを書いた経験のある人物であるべきです。 プロダクションレベルのスマートコントラクトは、初心者にとってのスタート地点ではありません。
プロダクトマネージャーやコミュニティとの設計に関する議論を主導し、コードやテストの大部分を書き、レビューの依頼を行い、要求された変更を行い、プロジェクトが期限内に完了させることがこの人物の責任であるべきです。
また、リーダーは、CLI を使用してトランザクションに署名し、スマートコントラクトをデプロイ/アップグレードする方法、管理トランザクションを実行する方法、問題のトラブルシューティング方法などを理解している必要があります。スマートコントラクトに関連して何か問題が発生し、カスタムトランザクションで対応する必要がある場合、オーナーがトランザクションやスクリプトを安全に構築および実行する方法を理解していることが重要です。
また、オリジナルのオーナーが利用できない場合やプロジェクトから離れる場合の明確な後継者計画も必要です。コードと要件を明確に理解し、適切なフィードバックを提供し、効果的なレビューを行い、必要に応じて変更を加えることができる人物が他にいることが重要です。
Projects should maintain a well-organized open source repository for their smart contracts
NBA Topshotのようなプロジェクトが示しているように、ブロックチェーン製品が成功を収めると、他の人々があなたのやっていることを土台にして構築することが可能になり、実際にそうなる。それが分析であれ、ツールであれ、あるいはあなたのプロジェクトのエコシステムを成長させるのに役立つその他の付加価値であれ、コンポーザビリティが鍵であり、それはオープンソース開発に依存する。まだオープンソースのリポジトリがない場合は、ビルダーはリポジトリを作成することを強く検討すべきである。
ビルダーは、Flowのオープンソーステンプレートから始め、コードを記述する前に、リポジトリの目的を説明する初期ドキュメントをリポジトリ全体に設定しておくべきです。外部の開発者やユーザーは、任意のプロジェクトを理解するために、簡単にアクセスできるホームページを持つべきです。
また、リポジトリにはスマートコントラクトの意図する設計とアーキテクチャを概説したハイレベルな設計文書も用意すべきです。プロジェクトのリーダーは、文書に含めるべき内容を決定すべきですが、有用な内容としては、基本的なユーザーストーリー、スマートコントラクトのアーキテクチャ、それについてまだ回答が必要な質問などが挙げられます。
-
該当する場合は、ステートマシンやユーザーフローなどを説明する図を作成すべきです。
-
この文書は、コントラクトまたは機能の開発が行われているオープンソースのリポジトリ内のissueで共有し、その後、READMEまたはその他の重要なドキュメントページに移動させるべきです。
高レベルの設計は、脅威をモデル化し、システムのリスクを理解する重要な機会となります。設計を共同で作成し、レビューするプロセスは、より多くのエッジケースを捕捉し、対処することを確実にするのに役立ちます。また、何百行ものCadenceのコードを修正するよりも、設計を繰り返し行う方がはるかに労力が少なくて済みます。
Development Process Recommendations
The Development process should be iterative if possible
プロジェクトでは、まずMVPを開発し、レビューを受け、徹底的にテストを行った上で、テストを行いながら追加機能を加えていくべきです。これにより、コア機能が慎重に設計されることが保証され、レビュープロセスも容易になります。膨大な量のコードに圧倒されることなく、各機能をひとつずつ確認できるからです。
Comments and field and function descriptions are essential
私たちは、Cadenceのスマートコントラクトを数多く作成する中で、ドキュメントがいかに重要であるかを学びました。特に、誰のために何をドキュメント化するかが重要であり、その点では他のソフトウェア言語と変わりません。例えば、あるコントラクトで発生したイベントが別のコントラクトの結果につながる場合など、その理由を記述することは非常に重要です。「何を」記述するかによって、コードがそのように動作する理由や背景が明らかになります。「どのように」記述するかは、ドキュメント化するのではなく、コードを記述することです。コメントは、後にコードを変更する人に向けて書くべきです。
コメントは、コードを記述するのと同時（またはそれ以前）に記述すべきです。これにより、開発者やレビュアーが、進行中のコードや設計の意図（テストやレビュー用）をより理解しやすくなります。関数には、以下のコメントを記述すべきです。
- 説明
- パラメータの説明
- 戻り値の説明
トップレベルのコメントおよび型、フィールド、イベント、関数に関するコメントには、Cadence Documentation Generatorで認識されるように、///（スラッシュ3つ）を使用すべきです。関数内の通常のコメントには、スラッシュ2つ（//）のみを使用すべきです。
Testing Recommendations
以下に、典型的なスマートコントラクトプロジェクトにおいて特筆すべきテスト関連の推奨事項をまとめます。
一般的なテストフレームワークには以下のようなものがあります。 Cadence: Cadence Testing Framework (Javascript: Flow JS Testing, Go: Overflow)
コードを書く人と同じ人がテストも書くべきです。 コードパスやエッジケースについて、最も明確な理解を持っているのはその人だからです。
コントラクトがどこかからコピーされたものであっても、テストはオプションではなく必須であるべきです。パブリックリポジトリには、徹底したエミュレーターのユニットテストが存在すべきです。Cadenceのユニットテストの例については、Flow fungible tokenリポジトリを参照してください。
Cadenceまたはエミュレーターのバージョンが新しくなるたびに、リポジトリの依存関係を更新し、すべてのテストが引き続き合格することを確認する必要があります。
テストは単一構造にならないようにすべきであり、個々のテストケースは、コントラクトの各部分に対して個別にテストできるように設定する必要があります。Go言語で書かれたテスト例については、FlowEpoch smart contract testsを参照してください。異なる機能ごとにテストケースが個別のブロックに分割されています。ただし、状態マシンを実行してさまざまなケースをテストする必要があるコントラクトなど、いくつかの例外があります。肯定的なケースと否定的なケースの両方をテストする必要があります。
また、アプリおよび/またはバックエンドがスマートコントラクトと適切にやりとりできることを確認するための統合テストも作成する必要があります。
Managing Project Keys and Deployments
スマートコントラクトのkeysとデプロイは非常に重要であり、そのように扱う必要があります。
Private Keys should be stored securely
スマートコントラクトのkeysとデプロイは非常に重要であり、そのように扱う必要があります。
Managing Project Keys and Deployments
コントラクトおよび/または管理アカウントの秘密鍵は、いかなる場合もプレーンテキスト形式で保存すべきではありません。プロジェクトは、秘密鍵の保存に最適な安全なソリューションを決定する必要があります。弊社では、google KMS などの安全なキーストアへの保存をお勧めします。
Deployments to Testnet or Mainnet should be handled transparently
プロジェクトが成功を収めるにつれ、その周囲のコミュニティも成長していきます。信頼を必要としないエコシステムでは、これはまた、あなたのコントラクトを基に構築する他の人々が増えることを意味します。コントラクトをデプロイまたはアップグレードする前に、変更は常にリスクを伴うものであるため、十分な通知期間を設けてコミュニティとのコミュニケーションを明確に保つことが重要です。アップグレードによる問題が発生する前に、コミュニティメンバーに時間を与えてレビューや対応を行ってもらうことで、プロジェクトに対する信頼と自信が生まれます。デプロイやアップグレードの管理方法について、いくつかの提案を紹介します。
- すべての利害関係者に十分な余裕をもって連絡する
- 少なくとも1週間前までに、コミュニティに提案を共有する（クリティカルなバグ修正でない場合
- 共有する場所の例としては、プロジェクトのチャット、フォーラム、ブログ、メーリングリストなどがあります。
- これにより、コミュニティやその他の利害関係者は、今後の変更を十分に確認し、必要に応じてフィードバックを提供することができます。
- デプロイの時間とデプロイのトランザクションをブランチ/コミットのハッシュ情報と共有し、トランザクション自体が正しいことを確認します。
- 利害関係者とデプロイを調整し、正しく、予定通りに完了していることを確認します。
- 少なくとも1週間前までに、コミュニティに提案を共有する（クリティカルなバグ修正でない場合
(他にもあります。詳しくは翻訳元の原文へ）
翻訳元->https://cadence-lang.org/docs/project-development-tips