From 3f25cbe44cb416cb633af01ed154b8a103a3dcc9 Mon Sep 17 00:00:00 2001 From: tbrooke Date: Sun, 22 Jun 2025 19:58:45 -0400 Subject: [PATCH 1/6] Initial change from Template Studio to Playground Signed-off-by: tbrooke --- website/i18n/en.json | 14 +++++------ website/pages/en/index.js | 2 +- website/sidebars.json | 2 +- website/siteConfig.js | 2 +- .../version-0.12/accordproject-studio.md | 6 ++--- .../version-0.12/advanced-hyperledger.md | 12 ++++----- .../version-0.20/accordproject-business.md | 2 +- .../version-0.20/ref-cicero-ui.md | 2 +- .../version-0.20/started-resources.md | 2 +- .../version-0.20/started-studio.md | 25 ++++++++++--------- .../version-0.20/tutorial-hyperledger.md | 16 ++++++------ .../version-0.20/tutorial-latedelivery.md | 2 +- .../version-0.21/accordproject-faq.md | 2 +- .../version-0.21/accordproject-tour.md | 2 +- .../version-0.21/tutorial-studio.md | 6 ++--- .../version-0.22/tutorial-studio.md | 8 +++--- .../version-0.30.1/accordproject-faq.md | 4 +-- .../version-0.30.1/accordproject-template.md | 2 +- .../version-0.30.1/started-resources.md | 2 +- .../version-0.20-sidebars.json | 2 +- 20 files changed, 58 insertions(+), 57 deletions(-) diff --git a/website/i18n/en.json b/website/i18n/en.json index 7cddeebf..9d180cba 100644 --- a/website/i18n/en.json +++ b/website/i18n/en.json @@ -6,13 +6,13 @@ "tagline": "Documentation", "docs": { "accordproject-faq": { - "title": "FAQ" + "title": "accordproject-faq" }, "accordproject-slc": { "title": "Smart Legal Contracts" }, "accordproject-template": { - "title": "Accord Project Templates" + "title": "accordproject-template" }, "accordproject-tour": { "title": "Online Tour" @@ -137,8 +137,8 @@ "tutorial-nodejs": { "title": "With Node.js" }, - "tutorial-studio": { - "title": "With Template Studio" + "tutorial-playground": { + "title": "With Template playground" }, "tutorial-templates": { "title": "Templates Deep Dive" @@ -156,7 +156,7 @@ "title": "Learning Resources" }, "version-0.12/version-0.12-accordproject-studio": { - "title": "Template Studio" + "title": "Template Playground" }, "version-0.12/version-0.12-accordproject-templates": { "title": "Open Source Templates" @@ -588,7 +588,7 @@ "title": "With Node.js" }, "version-0.21/version-0.21-tutorial-studio": { - "title": "With Template Studio" + "title": "With Template Playground" }, "version-0.21/version-0.21-tutorial-templates": { "title": "Templates Deep Dive" @@ -633,7 +633,7 @@ "title": "With Node.js" }, "version-0.22/version-0.22-tutorial-studio": { - "title": "With Template Studio" + "title": "With Template Playground" }, "version-0.22/version-0.22-tutorial-templates": { "title": "Templates Deep Dive" diff --git a/website/pages/en/index.js b/website/pages/en/index.js index afb1623b..17496ad8 100755 --- a/website/pages/en/index.js +++ b/website/pages/en/index.js @@ -204,7 +204,7 @@ const TryOut = props => ( {[ { content: - '
You can author and test templates online in the Accord Project Template Studio. Search for existing templates, edit the contract text and execute the logic.
', + '
You can author and test templates online in the Accord Project . Search for existing templates, edit the contract text and execute the logic.
', image: imgUrl("../docs/assets/020/studio.png"), imageAlt: "An example a template being edited. There is an option to edit the full contract or a single clause. There is also a search bar at the top center for users to search for specific templates.", diff --git a/website/sidebars.json b/website/sidebars.json index 27ecdd23..94c57982 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -28,7 +28,7 @@ { "type": "subcategory", "label": "Template Authoring", - "ids": ["tutorial-studio","tutorial-vscode"] + "ids": ["tutorial-playground","tutorial-vscode"] }, { "type": "subcategory", diff --git a/website/siteConfig.js b/website/siteConfig.js index 76763b70..6afe04d3 100644 --- a/website/siteConfig.js +++ b/website/siteConfig.js @@ -60,7 +60,7 @@ const siteConfig = { // For no header links in the top nav bar -> headerLinks: [], headerLinks: [ { doc: 'accordproject', label: 'Documentation' }, - { href: "https://studio.accordproject.org", label: "Try Online!"}, + { href: "https://playground.accordproject.org", label: "Try Online!"}, { href: "https://github.com/accordproject", label: "GitHub" }, { search: true }, ], diff --git a/website/versioned_docs/version-0.12/accordproject-studio.md b/website/versioned_docs/version-0.12/accordproject-studio.md index 5cdbbe6d..c4c52c32 100644 --- a/website/versioned_docs/version-0.12/accordproject-studio.md +++ b/website/versioned_docs/version-0.12/accordproject-studio.md @@ -1,9 +1,9 @@ --- id: version-0.12-accordproject-studio -title: Template Studio -original_id: accordproject-studio +title: Template Playground +original_id: accordproject-playground --- -[Template Studio](https://studio.accordproject.org) lets you create, edit and test legal clause or contract templates built with the Accord Project. +[Template Studio](https://playground.accordproject.org) lets you create, edit and test legal clause or contract templates built with the Accord Project. ![Model Repository](/img/studio.png) diff --git a/website/versioned_docs/version-0.12/advanced-hyperledger.md b/website/versioned_docs/version-0.12/advanced-hyperledger.md index c8fc8583..afa22c7f 100644 --- a/website/versioned_docs/version-0.12/advanced-hyperledger.md +++ b/website/versioned_docs/version-0.12/advanced-hyperledger.md @@ -57,23 +57,23 @@ Once you've provisioned your server, install all of the required tools using the - [Git](https://www.digitalocean.com/community/tutorials/how-to-install-git-on-ubuntu-18-04) - [Fabric](https://hyperledger-fabric.readthedocs.io/en/release-1.3/getting_started.html) -## Create your Smart Legal Contract with Template Studio +## Create your Smart Legal Contract with Template Playground -Cicero Templates are the magic glue that binds your clever legal words with the logic that will run on your network. In this first step, we'll create a template in [Template Studio](https://studio.accordproject.org/). +Cicero Templates are the magic glue that binds your clever legal words with the logic that will run on your network. In this first step, we'll create a template in [Template Playground](https://playground.accordproject.org/). -Template Studio is a browser-based development environment for Cicero Templates. Your templates are only every stored in your browser (and are not shared with the Accord Project), so you should **Export** your work to save it for another time. +Template Playground is a browser-based development environment for Cicero Templates. Your templates are only every stored in your browser (and are not shared with the Accord Project), so you should **Export** your work to save it for another time. This tutorial uses the `supplyagreement-perishable-goods` template. This Smart Legal Agreement combines a plaintext contract for the shipment of goods that impose conditions on temperature and humidity until the shipment is delivered. We simulate the submission of IoT events from sensors that get sent to the contract in a supply blockchain network. The contract determines the obligations and actions of the parties according to its logic and legal text. -Once you've connected to your system, open https://studio.accordproject.org in a new browser window. +Once you've connected to your system, open https://playground.accordproject.org in a new browser window. :::note In the hosted images, Mozilla Firefox is preinstalled, click the icon on the top-left toolbar to launch it. ::: -The Template Studio allows you to load sample templates for smart legal agreements from the [Accord Project template library](https://templates.accordproject.org/). +The Template Playground allows you to load sample templates for smart legal agreements from the [Accord Project template library](https://templates.accordproject.org/). > In the Template Studio search bar, type **supplyagreement-perishable-goods**. Select the 0.12.1 version. @@ -100,7 +100,7 @@ The _Obligations_ that are emitted by the contract are configured to be emitted Save your CTA (Cicero Template Archive) file somewhere safe, as you'll need to use it in a later step. We suggest saving the file in user's the home folder. -> Create a `request.json` file with the contents of the **Request** box from the **Logic** -> **Test Execution** page in Template Studio. +> Create a `request.json` file with the contents of the **Request** box from the **Logic** -> **Test Execution** page in . For example: ```json diff --git a/website/versioned_docs/version-0.20/accordproject-business.md b/website/versioned_docs/version-0.20/accordproject-business.md index 0e8469e7..ef534f4b 100644 --- a/website/versioned_docs/version-0.20/accordproject-business.md +++ b/website/versioned_docs/version-0.20/accordproject-business.md @@ -29,4 +29,4 @@ If you are new to the Accord Project, the best place to start is our [Online Tou If any of the technical terms are confusing or hard to understand, we have a [Glossary](ref-glossary) page that may help you. If there are any concepts or terms that you want to include in the Glossary, please join our [slack channel](https://accord-project-slack-signup.herokuapp.com/) and make suggestions! -If you want to create a template yourself, please see [Authoring in Template Studio](tutorial-latedelivery) for a step-by-step guide on how to create your first template. The tutorial will provide an accessible starting point for those without significant development experience to begin building smart legal contracts using the Accord Project technology. +If you want to create a template yourself, please see [Authoring in ](tutorial-latedelivery) for a step-by-step guide on how to create your first template. The tutorial will provide an accessible starting point for those without significant development experience to begin building smart legal contracts using the Accord Project technology. diff --git a/website/versioned_docs/version-0.20/ref-cicero-ui.md b/website/versioned_docs/version-0.20/ref-cicero-ui.md index 21e17b26..0f5cd1d1 100644 --- a/website/versioned_docs/version-0.20/ref-cicero-ui.md +++ b/website/versioned_docs/version-0.20/ref-cicero-ui.md @@ -6,7 +6,7 @@ original_id: ref-cicero-ui Accord Project publishes [React](https://reactjs.org) user interface components for use in web-applications. Please refer to the cicero-ui project [on GitHub](https://github.com/accordproject/cicero-ui) for detailed usage instructions. -You can preview these components in [Template Studio v2](https://accordproject-studio.netlify.com). +You can preview these components in [ v2](https://accordproject-studio.netlify.com). ![Template-Studio-V2](/docs/assets/reference/tsv2.png) diff --git a/website/versioned_docs/version-0.20/started-resources.md b/website/versioned_docs/version-0.20/started-resources.md index 823f7a2d..4d4f179c 100644 --- a/website/versioned_docs/version-0.20/started-resources.md +++ b/website/versioned_docs/version-0.20/started-resources.md @@ -24,7 +24,7 @@ Accord Project is also developing tools to help with authoring, testing and runn ### Editors -- [Template Studio](https://studio.accordproject.org/): a Web-based editor for Accord Project templates +- [Template Playground](https://playground.accordproject.org/): a Web-based editor for Accord Project templates - [VSCode Extension](https://marketplace.visualstudio.com/items?itemName=accordproject.cicero-vscode-extension): an Accord Project extension to the popular [Visual Studio Code](https://visualstudio.microsoft.com/) Editor - [Emacs Mode](https://github.com/accordproject/ergo/tree/master/ergo.emacs): Emacs Major mode for Ergo (alpha) - [VIM Plugin](https://github.com/accordproject/ergo/tree/master/ergo.vim): VIM plugin for Ergo (alpha) diff --git a/website/versioned_docs/version-0.20/started-studio.md b/website/versioned_docs/version-0.20/started-studio.md index e9fc596a..cdfc061c 100644 --- a/website/versioned_docs/version-0.20/started-studio.md +++ b/website/versioned_docs/version-0.20/started-studio.md @@ -4,33 +4,34 @@ title: Online Tour original_id: started-studio --- -To get an better acquainted with Accord Project templates, the easiest way is through the online [Template Studio](https://studio.accordproject.org) editor. +To get an better acquainted with Accord Project templates, the easiest way is through the online [Template Playground](https://playground.accordproject.org) editor. :::tip -You can open template studio from anywhere in this documentation by clicking the [Try Online!](https://studio.accordproject.org) button located in the top-right of the page. +You can open Templaate Playground from anywhere in this documentation by clicking the [Try Online!](https://playground.accordproject.org) button located in the top-right of the page. ::: -The following video offers a tour of Template Studio and an introduction to the key concepts behind the Accord Project technology. +The following video offers a tour of Template Playground and an introduction to the key concepts behind the Accord Project technology. - + + ## What next? -Learn more about authoring Accord Project templates in template studio with the [Editing a Late Delivery Clause](tutorial-latedelivery) tutorial. +Learn more about authoring Accord Project templates in with the [Editing a Late Delivery Clause](tutorial-latedelivery) tutorial. diff --git a/website/versioned_docs/version-0.20/tutorial-hyperledger.md b/website/versioned_docs/version-0.20/tutorial-hyperledger.md index d0af680c..79de6473 100644 --- a/website/versioned_docs/version-0.20/tutorial-hyperledger.md +++ b/website/versioned_docs/version-0.20/tutorial-hyperledger.md @@ -57,25 +57,25 @@ Once you've provisioned your server, install all of the required tools using the - [Git](https://www.digitalocean.com/community/tutorials/how-to-install-git-on-ubuntu-18-04) - [Fabric](https://hyperledger-fabric.readthedocs.io/en/release-1.3/getting_started.html) -## Create your Smart Legal Contract with Template Studio +## Create your Smart Legal Contract with Template Playground -Cicero Templates are the magic glue that binds your clever legal words with the logic that will run on your network. In this first step, we'll create a template in [Template Studio](https://studio.accordproject.org/). +Cicero Templates are the magic glue that binds your clever legal words with the logic that will run on your network. In this first step, we'll create a template in [Template Playground](https://playground.accordproject.org/). -Template Studio is a browser-based development environment for Cicero Templates. Your templates are only every stored in your browser (and are not shared with the Accord Project), so you should **Export** your work to save it for another time. +Template Playground is a browser-based development environment for Cicero Templates. Your templates are only every stored in your browser (and are not shared with the Accord Project), so you should **Export** your work to save it for another time. This tutorial uses the `supplyagreement-perishable-goods` template. This Smart Legal Agreement combines a plaintext contract for the shipment of goods that impose conditions on temperature and humidity until the shipment is delivered. We simulate the submission of IoT events from sensors that get sent to the contract in a supply blockchain network. The contract determines the obligations and actions of the parties according to its logic and legal text. -Once you've connected to your system, open https://studio.accordproject.org in a new browser window. +Once you've connected to your system, open https://playground.accordproject.org in a new browser window. :::note In the hosted images, Mozilla Firefox is preinstalled, click the icon on the top-left toolbar to launch it. ::: -The Template Studio allows you to load sample templates for smart legal agreements from the [Accord Project template library](https://templates.accordproject.org/). +The Template Playground allows you to load sample templates for smart legal agreements from the [Accord Project template library](https://templates.accordproject.org/). -> In the Template Studio search bar, type **supplyagreement-perishable-goods**. Select the 0.12.1 version. +> In the Template Playground search bar, type **supplyagreement-perishable-goods**. Select the 0.12.1 version. Explore the source components of the template. @@ -100,7 +100,7 @@ The _Obligations_ that are emitted by the contract are configured to be emitted Save your CTA (Cicero Template Archive) file somewhere safe, as you'll need to use it in a later step. We suggest saving the file in user's the home folder. -> Create a `request.json` file with the contents of the **Request** box from the **Logic** -> **Test Execution** page in Template Studio. +> Create a `request.json` file with the contents of the **Request** box from the **Logic** -> **Test Execution** page in Template Playground. For example: ```json @@ -123,7 +123,7 @@ For example: } ``` -Finally, create a `contract.txt` file with the contents of the Test Contract box from the Contract Text page in Template Studio. +Finally, create a `contract.txt` file with the contents of the Test Contract box from the Contract Text page in Template Playground. :::note It's important that your sample contract text exactly matches your grammar's structure, this includes trailing spaces and line breaks. To be sure that you copy everything, right click the window and choose Select All, before choosing Copy. diff --git a/website/versioned_docs/version-0.20/tutorial-latedelivery.md b/website/versioned_docs/version-0.20/tutorial-latedelivery.md index 604042a4..94e45bd7 100644 --- a/website/versioned_docs/version-0.20/tutorial-latedelivery.md +++ b/website/versioned_docs/version-0.20/tutorial-latedelivery.md @@ -4,7 +4,7 @@ title: Editing a Late Delivery Clause original_id: tutorial-latedelivery --- -This tutorial will walk you through the steps of authoring a clause template in [Template Studio](https://studio.accordproject.org/). +This tutorial will walk you through the steps of authoring a clause template in [](https://studio.accordproject.org/). We start with a very simple _Late Penalty and Delivery_ Clause and gradually make it more complex, adding both legal text to it and the corresponding business logic in Ergo. diff --git a/website/versioned_docs/version-0.21/accordproject-faq.md b/website/versioned_docs/version-0.21/accordproject-faq.md index a792922c..c45b71e3 100644 --- a/website/versioned_docs/version-0.21/accordproject-faq.md +++ b/website/versioned_docs/version-0.21/accordproject-faq.md @@ -51,7 +51,7 @@ The Accord Project Community is developing several working groups focusing on di A primary purpose of the working groups is to develop a universally accessible and widely used open source library of modular, smart legal contracts, smart templates and models that reflect input from the community. Smart legal contract templates are built according to the Project’s [Cicero Specification](https://github.com/accordproject/cicero). -Members can provide feedback into the templates and models relevant to a particular working group. You can immediately start contributing smart legal contract templates and models by using the Accord Project’s [Template Studio](https://studio.accordproject.org/). +Members can provide feedback into the templates and models relevant to a particular working group. You can immediately start contributing smart legal contract templates and models by using the Accord Project’s [Template Playground](https://playground.accordproject.org/). The Accord Project has developed an easy-to-use programming language for building and executing smart legal contracts called Ergo. The goals of Ergo are to be accessible and usable by non-technical professionals, portable across, and compatible with, a variety of environments such as SaaS platforms and different blockchains, and meeting security, safety, and other requirements. diff --git a/website/versioned_docs/version-0.21/accordproject-tour.md b/website/versioned_docs/version-0.21/accordproject-tour.md index 68bfed33..95ccb544 100644 --- a/website/versioned_docs/version-0.21/accordproject-tour.md +++ b/website/versioned_docs/version-0.21/accordproject-tour.md @@ -4,7 +4,7 @@ title: Online Tour original_id: accordproject-tour --- -To get an better acquainted with Accord Project templates, the easiest way is through the online [Template Studio](https://studio.accordproject.org) editor. +To get an better acquainted with Accord Project templates, the easiest way is through the online [Template Playground](https://playground.accordproject.org) editor. :::tip You can open template studio from anywhere in this documentation by clicking the [Try Online!](https://studio.accordproject.org) button located in the top-right of the page. diff --git a/website/versioned_docs/version-0.21/tutorial-studio.md b/website/versioned_docs/version-0.21/tutorial-studio.md index 082c09a9..9df8ca1f 100644 --- a/website/versioned_docs/version-0.21/tutorial-studio.md +++ b/website/versioned_docs/version-0.21/tutorial-studio.md @@ -1,10 +1,10 @@ --- id: version-0.21-tutorial-studio -title: With Template Studio -original_id: tutorial-studio +title: With Template Playground +original_id: tutorial-playground --- -This tutorial will walk you through the steps of editing a clause template in [Template Studio](https://studio.accordproject.org/). +This tutorial will walk you through the steps of editing a clause template in [Template Playground](https://playground.accordproject.org/). We start with a very simple _Late Penalty and Delivery_ Clause and gradually make it more complex, adding both legal text to it and the corresponding business logic in Ergo. diff --git a/website/versioned_docs/version-0.22/tutorial-studio.md b/website/versioned_docs/version-0.22/tutorial-studio.md index fbd57320..e40f176d 100644 --- a/website/versioned_docs/version-0.22/tutorial-studio.md +++ b/website/versioned_docs/version-0.22/tutorial-studio.md @@ -1,10 +1,10 @@ --- id: version-0.22-tutorial-studio -title: With Template Studio -original_id: tutorial-studio +title: With Template Playground +original_id: tutorial-playground --- -This tutorial will walk you through the steps of editing a clause template in [Template Studio](https://studio.accordproject.org/). +This tutorial will walk you through the steps of editing a clause template in [Template Playground](https://playground.accordproject.org/). We start with a very simple _Late Penalty and Delivery_ Clause and gradually make it more complex, adding both legal text to it and the corresponding business logic in Ergo. @@ -12,7 +12,7 @@ We start with a very simple _Late Penalty and Delivery_ Clause and gradually mak ### Load the Template -To get started, head to the `minilatedeliveryandpenalty` template in the Accord Project Template Library at [Mini Late Delivery And Penalty](https://templates.accordproject.org/minilatedeliveryandpenalty@0.6.0.html) and click the "Open In Template Studio" button. +To get started, head to the `minilatedeliveryandpenalty` template in the Accord Project Template Library at [Mini Late Delivery And Penalty](https://templates.accordproject.org/minilatedeliveryandpenalty@0.6.0.html) and click the "Open In Template Playground" button. ![Advanced-Late-1](assets/advanced/late1.png) diff --git a/website/versioned_docs/version-0.30.1/accordproject-faq.md b/website/versioned_docs/version-0.30.1/accordproject-faq.md index 8cd09c0d..6fbf9d6b 100644 --- a/website/versioned_docs/version-0.30.1/accordproject-faq.md +++ b/website/versioned_docs/version-0.30.1/accordproject-faq.md @@ -51,9 +51,9 @@ The Accord Project Community is developing several working groups focusing on di A primary purpose of the working groups is to develop a universally accessible and widely used open source library of modular, smart legal contracts, smart templates and models that reflect input from the community. Smart legal contract templates are built according to the Project’s [Cicero Specification](https://github.com/accordproject/cicero). -Members can provide feedback into the templates and models relevant to a particular working group. You can immediately start contributing smart legal contract templates and models by using the Accord Project’s [Template Studio](https://studio.accordproject.org/). +Members can provide feedback into the templates and models relevant to a particular working group. You can immediately start contributing smart legal contract templates and models by using the Accord Project’s [Template Playground](https://playground.accordproject.org/). The Accord Project has developed an easy-to-use programming language for building and executing smart legal contracts called Ergo. The goals of Ergo are to be accessible and usable by non-technical professionals, portable across, and compatible with, a variety of environments such as SaaS platforms and different blockchains, and meeting security, safety, and other requirements. -You can use the Accord Project’s [Template Studio](https://studio.accordproject.org/) to create and test your smart legal contracts. +You can use the Accord Project’s [Template Playground](https://playground.accordproject.org/) to create and test your smart legal contracts. diff --git a/website/versioned_docs/version-0.30.1/accordproject-template.md b/website/versioned_docs/version-0.30.1/accordproject-template.md index 6bfa179e..970ed3ca 100644 --- a/website/versioned_docs/version-0.30.1/accordproject-template.md +++ b/website/versioned_docs/version-0.30.1/accordproject-template.md @@ -206,7 +206,7 @@ Let's look at each component of the template triangle, starting with the text. ### What next? -Build your first smart legal contract templates, either [online](tutorial-studio.md) with Template Studio, or by [installing Cicero](started-installation.md). +Build your first smart legal contract templates, either [online](tutorial-studio.md) with Template Playground, or by [installing Cicero](started-installation.md). Explore [sample templates](started-resources.md) and other resources in the rest of this documentation. diff --git a/website/versioned_docs/version-0.30.1/started-resources.md b/website/versioned_docs/version-0.30.1/started-resources.md index 60794a02..420cb52a 100644 --- a/website/versioned_docs/version-0.30.1/started-resources.md +++ b/website/versioned_docs/version-0.30.1/started-resources.md @@ -24,7 +24,7 @@ Accord Project is also developing tools to help with authoring, testing and runn ### Editors -- [Template Studio](https://studio.accordproject.org/): a Web-based editor for Accord Project templates +- [Template Playground](https://playground.accordproject.org/): a Web-based editor for Accord Project templates - [VSCode Extension](https://marketplace.visualstudio.com/items?itemName=accordproject.cicero-vscode-extension): an Accord Project extension to the popular [Visual Studio Code](https://visualstudio.microsoft.com/) Editor - [Emacs Mode](https://github.com/accordproject/ergo/tree/master/ergo.emacs): Emacs Major mode for Ergo (alpha) - [VIM Plugin](https://github.com/accordproject/ergo/tree/master/ergo.vim): VIM plugin for Ergo (alpha) diff --git a/website/versioned_sidebars/version-0.20-sidebars.json b/website/versioned_sidebars/version-0.20-sidebars.json index 9f30ec6f..b7c99a1c 100644 --- a/website/versioned_sidebars/version-0.20-sidebars.json +++ b/website/versioned_sidebars/version-0.20-sidebars.json @@ -15,7 +15,7 @@ "User Tutorials": [ { "type": "subcategory", - "label": "Authoring with Template Studio", + "label": "Authoring with ", "ids": [ "version-0.20-tutorial-latedelivery" ] From a95852f19cc3579145ccb8bec0a4c698e9357686 Mon Sep 17 00:00:00 2001 From: tbrooke Date: Sun, 22 Jun 2025 19:59:08 -0400 Subject: [PATCH 2/6] Initial change from Template Studio to Playground Signed-off-by: tbrooke --- docs/accordproject-faq.md | 1 + docs/accordproject-template.md | 2 +- docs/accordproject-tour.md | 17 ++++++++--------- ...utorial-studio.md => tutorial-playground.md} | 8 ++++---- 4 files changed, 14 insertions(+), 14 deletions(-) rename docs/{tutorial-studio.md => tutorial-playground.md} (96%) diff --git a/docs/accordproject-faq.md b/docs/accordproject-faq.md index 423e2d69..82e730ab 100644 --- a/docs/accordproject-faq.md +++ b/docs/accordproject-faq.md @@ -1,3 +1,4 @@ +**** --- id: accordproject-faq title: FAQ diff --git a/docs/accordproject-template.md b/docs/accordproject-template.md index fb7c2543..d3b3000d 100644 --- a/docs/accordproject-template.md +++ b/docs/accordproject-template.md @@ -1,4 +1,4 @@ ---- +****--- id: accordproject-template title: Accord Project Templates --- diff --git a/docs/accordproject-tour.md b/docs/accordproject-tour.md index 8c5136a2..f10eb33a 100644 --- a/docs/accordproject-tour.md +++ b/docs/accordproject-tour.md @@ -6,27 +6,26 @@ title: Online Tour To get better acquainted with Accord Project templates, the easiest way is through the online [Template Studio](https://studio.accordproject.org) editor. :::tip -You can open template studio from anywhere in this documentation by clicking the [Try Online!](https://studio.accordproject.org) button located in the top-right of the page. +You can open template playground from anywhere in this documentation by clicking the [Try Online!]( Here is a timestamp of what is covered in the video: -- **00:08** : Introduction to template Studio & pointers the other parts of the docs / AP website +- **00:08** : Introduction to template playground & pointers the other parts of the docs / AP website - **03:51** : Helloworld template tutorial start -- **04:48** : Template Studio - Metadata -- **06:56** : Template Studio - Contract Text +- **04:48** : Template Playground - Metadata +- **06:56** : Template Playground - Contract Text - **07:52** : The 'live' nature of the text; how to read errors - **08:39** : Changing the template text itself - **09:17** : Changing the variables in the template text -- **10:00** : Template Studio - Model update -- **11:28** : Template Studio - Logic update +- **10:00** : Template Playground - Model update +- **11:28** : Template Playground - Logic update - **13:17** : Explanation about request types / response types -- **14:44** : Template Studio - Logic - Test Execution (request, response) +- **14:44** : Template Playground - Logic - Test Execution (request, response) - **15:57** : Test Execution - contract state - **16:49** : Test Execution - obligations - **18:20** : Wrap-up - diff --git a/docs/tutorial-studio.md b/docs/tutorial-playground.md similarity index 96% rename from docs/tutorial-studio.md rename to docs/tutorial-playground.md index 47386834..beb00629 100644 --- a/docs/tutorial-studio.md +++ b/docs/tutorial-playground.md @@ -1,9 +1,9 @@ --- -id: tutorial-studio -title: With Template Studio +id: tutorial-playground +title: With Template playground --- -This tutorial will walk you through the steps of editing a clause template in [Template Studio](https://studio.accordproject.org/). +This tutorial will walk you through the steps of editing a clause template in [Template Playground](https://playground.accordproject.org/). We start with a very simple _Late Penalty and Delivery_ Clause and gradually make it more complex, adding both legal text to it and the corresponding business logic in Ergo. @@ -11,7 +11,7 @@ We start with a very simple _Late Penalty and Delivery_ Clause and gradually mak ### Load the Template -To get started, head to the `minilatedeliveryandpenalty` template in the Accord Project Template Library at [Mini Late Delivery And Penalty](https://templates.accordproject.org/minilatedeliveryandpenalty@0.6.0.html) and click the "Open In Template Studio" button. +To get started, head to the `minilatedeliveryandpenalty` template in the Accord Project Template Library at [Mini Late Delivery And Penalty](https://templates.accordproject.org/minilatedeliveryandpenalty@0.6.0.html) and click the "Open In Template Playground" button. ![Advanced-Late-1](assets/advanced/late1.png) From 9febb26af934ff34f56b288acf77091f41bf620a Mon Sep 17 00:00:00 2001 From: tbrooke Date: Sun, 22 Jun 2025 21:51:21 -0400 Subject: [PATCH 3/6] further updates studio => playground Signed-off-by: tbrooke --- website/sidebars.json | 53 ++++++++++++++++++++----------------------- 1 file changed, 24 insertions(+), 29 deletions(-) diff --git a/website/sidebars.json b/website/sidebars.json index 94c57982..e012dafc 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -4,73 +4,68 @@ "Getting Started": ["started-installation", "started-hello", "started-resources"], "Template Guides": [ { - "type": "subcategory", + "type": "category", "label": "Markdown Text", - "ids": ["markup-preliminaries", "markup-commonmark", "markup-ciceromark", "markup-templatemark"] + "items": ["markup-preliminaries", "markup-commonmark", "markup-ciceromark", "markup-templatemark"] }, { - "type": "subcategory", - "label": "Concerto Model", - "ids": ["model-concerto", "model-vocabulary", "model-namespaces", "model-classes", "model-enums", "model-properties", "model-relationships", "model-decorators", "model-api"] - }, - { - "type": "subcategory", + "type": "category", "label": "Ergo Logic", - "ids": ["logic-ergo", "logic-simple-expr", "logic-simple-type", "logic-complex-type", "logic-advanced-expr", "logic-stmt", "logic-decl", "logic-module"] + "items": ["logic-ergo", "logic-simple-expr", "logic-simple-type", "logic-complex-type", "logic-advanced-expr", "logic-stmt", "logic-decl", "logic-module"] } ], "Tutorials": [ { - "type": "subcategory", + "type": "category", "label": "Using Cicero", - "ids": ["tutorial-templates", "tutorial-library", "tutorial-create"] + "items": ["tutorial-templates", "tutorial-library", "tutorial-create"] }, { - "type": "subcategory", + "type": "category", "label": "Template Authoring", - "ids": ["tutorial-playground","tutorial-vscode"] + "items": ["tutorial-playground","tutorial-vscode"] }, { - "type": "subcategory", + "type": "category", "label": "Template Execution", - "ids": ["tutorial-nodejs", "tutorial-hyperledger"] + "items": ["tutorial-nodejs", "tutorial-hyperledger"] } ], "Reference Manual": [ { - "type": "subcategory", + "type": "category", "label": "General", - "ids": ["ref-glossary", "ref-errors"] + "items": ["ref-glossary", "ref-errors"] }, { - "type": "subcategory", + "type": "category", "label": "Migration", - "ids": ["ref-migrate-0.13-0.20", "ref-migrate-0.20-0.21", "ref-migrate-0.21-0.22", "ref-migrate-concerto-0.82-1.0", "ref-migrate-concerto-1.0-2.0", "ref-migrate-concerto-2.0-3.0"] + "items": ["ref-migrate-0.13-0.20", "ref-migrate-0.20-0.21", "ref-migrate-0.21-0.22"] }, { - "type": "subcategory", + "type": "category", "label": "Cicero Reference", - "ids": ["ref-cicero-cli", "ref-cicero-api", "ref-cicero-testing"] + "items": ["ref-cicero-cli", "ref-cicero-api", "ref-cicero-testing"] }, { - "type": "subcategory", + "type": "category", "label": "Markdown Transform Reference", - "ids": ["ref-markus-cli"] + "items": ["ref-markus-cli"] }, { - "type": "subcategory", + "type": "category", "label": "Concerto Reference", - "ids": ["ref-concerto-decorators", "ref-concerto-cli", "ref-concerto-api"] + "items": ["ref-concerto-decorators", "ref-concerto-cli", "ref-concerto-api"] }, { - "type": "subcategory", + "type": "category", "label": "Ergo Reference", - "ids": ["ref-ergo-stdlib", "ref-ergo-cli", "ref-ergo-repl", "ref-ergo-api", "ref-ergo-spec"] + "items": ["ref-ergo-stdlib", "ref-ergo-cli", "ref-ergo-repl", "ref-ergo-api", "ref-ergo-spec"] }, { - "type": "subcategory", + "type": "category", "label": "Web Components Reference", - "ids": ["ref-web-components-overview"] + "items": ["ref-web-components-overview"] } ] } From 98ba35ebfd0815a5a9665707abd1749a615ea653 Mon Sep 17 00:00:00 2001 From: tbrooke Date: Sun, 22 Jun 2025 21:51:36 -0400 Subject: [PATCH 4/6] further updates studio => playground Signed-off-by: tbrooke --- docs/accordproject-faq.md | 3 + docs/accordproject-template.md | 3 + docs/ergo-tutorial.md | 498 +++++++++++++++--------------- docs/tutorial-playground.md | 542 ++++++++++++++++----------------- 4 files changed, 526 insertions(+), 520 deletions(-) diff --git a/docs/accordproject-faq.md b/docs/accordproject-faq.md index 82e730ab..cca0046a 100644 --- a/docs/accordproject-faq.md +++ b/docs/accordproject-faq.md @@ -1,3 +1,6 @@ +--- + +--- **** --- id: accordproject-faq diff --git a/docs/accordproject-template.md b/docs/accordproject-template.md index d3b3000d..d3159b69 100644 --- a/docs/accordproject-template.md +++ b/docs/accordproject-template.md @@ -1,3 +1,6 @@ +--- + +--- ****--- id: accordproject-template title: Accord Project Templates diff --git a/docs/ergo-tutorial.md b/docs/ergo-tutorial.md index c2d021ab..0b9fa762 100644 --- a/docs/ergo-tutorial.md +++ b/docs/ergo-tutorial.md @@ -1,249 +1,249 @@ ---- -id: ergo-tutorial -title: Ergo: A Tutorial ---- - -## Overview of Accord - -Cicero is an Open Source implementation of the Accord Project Template Specification. It defines the structure of natural language templates, bound to a data model, that can be executed using Ergo and request/response JSON messages. You can read the latest user documentation here: http://docs.accordproject.org. - -In short, with the Accord Project you can take a classic contract, e.g. Word document and use Cicero to define natural language contract and clause templates that can be executed by an event driven computer program (aka Smart contract). For the tutorial, Cicero will be used to define natural language contract and clause templates. These clause templates handle the syllogistic language of contracts. - -For example, -```md - if the goods are more than [{DAYS}] late, - then notify the supplier of the goods, with the message [{MESSAGE}]. -``` -DAYS and MESSAGE are variables - -You can browse the library of Open Source Cicero contract and clause templates at: https://templates.accordproject.org. - -So how does the contract get executed? That is where Ergo comes in. Ergo is a strongly-typed functional programming language designed to capture the legal intent of legal contracts and clauses. We will use Ergo to create the contract logic consisting of a contract class with executable embedded clauses. Note: prior to the emergence of Ergo, the Cicero JavaScript component was primary to the execution of code. - -Ergo obviates the Cicero JavaScript component for the execution phase with a new more comprehensive language which we explore in this tutorial. - -## Cicero - -The Open Source Cicero project defines the format of clause and contract templates based on to the Cicero Template Specification. The templates are the link between the natural language of contracts usually composed in a Word document and the specification of a machine executable transaction. Cicero templates define the API by specifying request and response elements for the logic associated with functional transaction executed by Ergo. - -Cicero templates are composed of two elements: -* Template Grammar (the natural language text for the template), -* Template Model (the data model that includes the variables contained within the template). -* The Logic (the executable business logic for the template) will be handled by Ergo. - -When combined these three elements allow templates to be edited, analyzed, queried and executed. - -## Setup Ergo Development environment - -Before you can build Ergo, you must install and configure the following dependencies on your machine: - -### Git - -* Git: The [Github Guide to Installing Git][git-setup.md] is a good source of information. - -### Node.js - -* Node.js (LTS): We use Node to generate the documentation, run a development web server, run tests, and generate distributable files. Depending on your system, you can install Node either from source or as a pre-packaged bundle. -> Tip: Use nvm (or nvm-windows) to manage and install Node.js, This facilitates a version change of Node.js per project. -* Lerna: This is a tool which helps when handling multiple npm packages in the Ergo repository. To install: -npm install -g lerna@^3.15.0 - -### Visual Studio Code - -Visual Studio Code is a lightweight but powerful source code editor which runs on your desktop and is available for Windows, macOS and Linux. It comes with built-in support for JavaScript and Node.js and has a rich ecosystem of extensions for other languages (such Ergo). - -Follow the platform specific guides below: -See, https://code.visualstudio.com/docs/setup/ -* macOS -* Linux -* Windows - -#### Install Ergo Visual Studio Plugin - -### Validate Development Environment and Toolset - -Clone https://github.com/accordproject/ergo to your local machine - -### Getting started - -Install Ergo - -The easiest way to install Ergo is as a Node.js package. Once you have Node.js installed on your machine, you can get the Ergo compiler and command-line using the Node.js package manager by typing the following in a terminal: -$ npm install -g @accordproject/ergo-cli@0.20 - -This will install the compiler itself (ergoc) and a command-line tool (ergo) to execute Ergo code. You can check that both have been installed and print the version number by typing the following in a terminal: -```sh -$ ergoc --version -$ ergo --version -``` -Then, to get command line help: -``` -$ ergoc --help -$ ergo execute --help -``` -Compiling your first contract -```ergo -namespace org.accordproject.volumediscount - -contract VolumeDiscount over VolumeDiscountContract { - // Clause for volume discount - clause volumediscount(request : VolumeDiscountRequest) : VolumeDiscountResponse { - if request.netAnnualChargeVolume < contract.firstVolume - then return VolumeDiscountResponse{ discountRate: contract.firstRate } - else if request.netAnnualChargeVolume < contract.secondVolume - then return VolumeDiscountResponse{ discountRate: contract.secondRate } - else return VolumeDiscountResponse{ discountRate: contract.thirdRate } - } -} -``` - -To compile your first Ergo contract to JavaScript , within Visual Studio code -* Open the folder where you cloned https://github.com/accordproject/ergo -* Use View/Terminal to run the Ergo compiler: -```sh -$ ergoc ./examples/volumediscount/model.cto ./examples/volumediscount/logic.ergo -Compiling Ergo './examples/volumediscount/logic.ergo' -- creating './examples/volumediscount/logic.js' -``` - -By default, Ergo compiles to JavaScript for execution. This may change in the future to support other languages. The compiled code for the result in stored as `./examples/volumediscount/logic.js` - -### Execute a contract -To execute a contract, we pass the necessary parameters including the CTO, Ergo files, the name of a contract and the json files containing request and contract state -ergorun [ctos] [ergos] --contractname [file] --contract [file] --state [file] --request [file] - -So for example we use ergorun with : -```sh -$ ergorun ./examples/volumediscount/model.cto ./examples/volumediscount/logic.ergo ---contractname org.accordproject.volumediscount.VolumeDiscount ---contract ./examples/volumediscount/contract.json ---request ./examples/volumediscount/request.json ---state ./examples/volumediscount/state.json -``` - -Here contract.json contains the following values -```json -{ - "$class": "org.accordproject.volumediscount.VolumeDiscountContract", - "parties": null, - "contractId": "cr1", - "firstVolume": 1, - "secondVolume": 10, - "firstRate": 3, - "secondRate": 2.9, - "thirdRate": 2.8 -} -``` - -Request.json contains -```json -{ - "$class": "org.accordproject.volumediscount.VolumeDiscountRequest", - "netAnnualChargeVolume": 10.4 -} -``` - -logic.ergo contains: -```ergo -namespace org.accordproject.volumediscount - -contract VolumeDiscount over VolumeDiscountContract { - // Clause for volume discount - clause volumediscount(request : VolumeDiscountRequest) : VolumeDiscountResponse { - if request.netAnnualChargeVolume < contract.firstVolume - then return VolumeDiscountResponse{ discountRate: contract.firstRate } - else if request.netAnnualChargeVolume < contract.secondVolume - then return VolumeDiscountResponse{ discountRate: contract.secondRate } - else return VolumeDiscountResponse{ discountRate: contract.thirdRate } - } -} -``` - -Here netAnnualCharge Volume equals 10.4 which is not less than firstVolume and secondVolume which are equal to 1 and 10 respectively so the logic for the volumediscount clause returns thirdRate which equals 2.8 - -``` -7:31:58 PM - info: Logging initialized. 2018-09-27T23:31:58.623Z -7:31:59 PM - info: {"response":{"discountRate":2.8,"$class":"org.accordproject.volumediscount.VolumeDiscountResponse"},"state":{"$class":"org.accordproject.cicero.contract.AccordContractState","stateId":"1"},"emit":[]} -``` - -PS D:\Users\jbambara\Github\ergo> - -## Ergo Development - -Create Template -Start with basic agreement in natural language and locate the variables -Here in the example see the bold -Volume-Based Card Acceptance Agreement [Abbreviated] -This Agreement is by and between ………..you agree to be bound by the Agreement. -Discount means an amount that we charge you for accepting the Card, which amount is: -(i) a percentage (Discount Rate) of the face amount of the Charge that you submit, or a flat per- -Transaction fee, or a combination of both; and/or -(ii) a Monthly Flat Fee (if you meet our requirements). - -Transaction Processing and Payments. ………………… less all applicable deductions, rejections, and withholdings, which include: -…………………………. - -SETTLEMENT -a) Settlement Amount. Our agent will pay you according to your payment plan, ……………………..which include: - (i) the Discount, -………………………………………….. -b) Discount. The Discount is determined according to the following table: - -| Annual Dollar Volume | Discount | -| Less than $1 million | 3.00% | -| $1 million to $10 million | 2.90% | -| Greater than $10 million | 2.80% | -Identify the request variables and contract instance variables -Codify the variables with $[{request}] or [{contract instance}] -| Annual Dollar Volume | Discount | -| Less than $[{firstVolume}] million | [{firstRate}]% | -| $[{firstVolume}] million to $[{secondVolume}] million | [{secondRate}]% | -| Greater than $[{secondVolume}] million | [{thirdRate}]% | - -Create Model -Define the model asset which contains the contract instance variables and the transaction request and response. Defines the data model for the VolumeDiscount template. This defines the structure that the parser for the template generates from input source text. See model.cto below: - namespace org.accordproject.volumediscount -import org.accordproject.cicero.contract.* from https://models.accordproject.org/cicero/contract.cto -import org.accordproject.cicero.runtime.* from https://models.accordproject.org/cicero/runtime.cto -asset VolumeDiscountContract extends AccordContract { - o Double firstVolume - o Double secondVolume - o Double firstRate - o Double secondRate - o Double thirdRate -} -transaction VolumeDiscountRequest { - o Double netAnnualChargeVolume -} -transaction VolumeDiscountResponse { - o Double discountRate -} - -Create Logic -The contract logic is accomplished by coding ERGO statements and expressions to consume the request and use contract instance variables to produce the desired response. In our example, request.netAnnualChargeVolume is tested against contract rates to produce the result. -namespace org.accordproject.volumediscount - -define the contract -contract VolumeDiscount over VolumeDiscountContract { - -define the contract clause and request : response - - clause volumediscount(request : VolumeDiscountRequest) : VolumeDiscountResponse { - -define the logic ; here we use if /then /else statement to test request parameter against contract instance variable - and return - - if request.netAnnualChargeVolume < contract.firstVolume - then return VolumeDiscountResponse{ discountRate: contract.firstRate } - else if request.netAnnualChargeVolume < contract.secondVolume - then return VolumeDiscountResponse{ discountRate: contract.secondRate } - else return VolumeDiscountResponse{ discountRate: contract.thirdRate } - } - -Ergo Language -As you have seen in this tutorial, Ergo is a domain-specific language (DSL) that captures the execution logic of legal contracts. In this simple example, you see that Ergo aims to have contracts and clauses as first-class elements of the language. To accommodate the maturation of distributed ledger implementations, Ergo will be blockchain neutral, i.e., the same contract logic can be executed either on and off chain on distributed ledger technologies like HyperLedger Fabric. Most importantly, Ergo is consistent with the Accord Protocol Template Specification. Follow the links below to learn more about -Introduction to Ergo -Ergo Language Guide -Ergo Reference Guide - - -October 12, 2018 +--- +id: ergo-tutorial +title: "Ergo: A Tutorial" +--- + +## Overview of Accord + +Cicero is an Open Source implementation of the Accord Project Template Specification. It defines the structure of natural language templates, bound to a data model, that can be executed using Ergo and request/response JSON messages. You can read the latest user documentation here: http://docs.accordproject.org. + +In short, with the Accord Project you can take a classic contract, e.g. Word document and use Cicero to define natural language contract and clause templates that can be executed by an event driven computer program (aka Smart contract). For the tutorial, Cicero will be used to define natural language contract and clause templates. These clause templates handle the syllogistic language of contracts. + +For example, +```md + if the goods are more than [{DAYS}] late, + then notify the supplier of the goods, with the message [{MESSAGE}]. +``` +DAYS and MESSAGE are variables + +You can browse the library of Open Source Cicero contract and clause templates at: https://templates.accordproject.org. + +So how does the contract get executed? That is where Ergo comes in. Ergo is a strongly-typed functional programming language designed to capture the legal intent of legal contracts and clauses. We will use Ergo to create the contract logic consisting of a contract class with executable embedded clauses. Note: prior to the emergence of Ergo, the Cicero JavaScript component was primary to the execution of code. + +Ergo obviates the Cicero JavaScript component for the execution phase with a new more comprehensive language which we explore in this tutorial. + +## Cicero + +The Open Source Cicero project defines the format of clause and contract templates based on to the Cicero Template Specification. The templates are the link between the natural language of contracts usually composed in a Word document and the specification of a machine executable transaction. Cicero templates define the API by specifying request and response elements for the logic associated with functional transaction executed by Ergo. + +Cicero templates are composed of two elements: +* Template Grammar (the natural language text for the template), +* Template Model (the data model that includes the variables contained within the template). +* The Logic (the executable business logic for the template) will be handled by Ergo. + +When combined these three elements allow templates to be edited, analyzed, queried and executed. + +## Setup Ergo Development environment + +Before you can build Ergo, you must install and configure the following dependencies on your machine: + +### Git + +* Git: The [Github Guide to Installing Git][git-setup.md] is a good source of information. + +### Node.js + +* Node.js (LTS): We use Node to generate the documentation, run a development web server, run tests, and generate distributable files. Depending on your system, you can install Node either from source or as a pre-packaged bundle. +> Tip: Use nvm (or nvm-windows) to manage and install Node.js, This facilitates a version change of Node.js per project. +* Lerna: This is a tool which helps when handling multiple npm packages in the Ergo repository. To install: +npm install -g lerna@^3.15.0 + +### Visual Studio Code + +Visual Studio Code is a lightweight but powerful source code editor which runs on your desktop and is available for Windows, macOS and Linux. It comes with built-in support for JavaScript and Node.js and has a rich ecosystem of extensions for other languages (such Ergo). + +Follow the platform specific guides below: +See, https://code.visualstudio.com/docs/setup/ +* macOS +* Linux +* Windows + +#### Install Ergo Visual Studio Plugin + +### Validate Development Environment and Toolset + +Clone https://github.com/accordproject/ergo to your local machine + +### Getting started + +Install Ergo + +The easiest way to install Ergo is as a Node.js package. Once you have Node.js installed on your machine, you can get the Ergo compiler and command-line using the Node.js package manager by typing the following in a terminal: +$ npm install -g @accordproject/ergo-cli@0.20 + +This will install the compiler itself (ergoc) and a command-line tool (ergo) to execute Ergo code. You can check that both have been installed and print the version number by typing the following in a terminal: +```sh +$ ergoc --version +$ ergo --version +``` +Then, to get command line help: +``` +$ ergoc --help +$ ergo execute --help +``` +Compiling your first contract +```ergo +namespace org.accordproject.volumediscount + +contract VolumeDiscount over VolumeDiscountContract { + // Clause for volume discount + clause volumediscount(request : VolumeDiscountRequest) : VolumeDiscountResponse { + if request.netAnnualChargeVolume < contract.firstVolume + then return VolumeDiscountResponse{ discountRate: contract.firstRate } + else if request.netAnnualChargeVolume < contract.secondVolume + then return VolumeDiscountResponse{ discountRate: contract.secondRate } + else return VolumeDiscountResponse{ discountRate: contract.thirdRate } + } +} +``` + +To compile your first Ergo contract to JavaScript , within Visual Studio code +* Open the folder where you cloned https://github.com/accordproject/ergo +* Use View/Terminal to run the Ergo compiler: +```sh +$ ergoc ./examples/volumediscount/model.cto ./examples/volumediscount/logic.ergo +Compiling Ergo './examples/volumediscount/logic.ergo' -- creating './examples/volumediscount/logic.js' +``` + +By default, Ergo compiles to JavaScript for execution. This may change in the future to support other languages. The compiled code for the result in stored as `./examples/volumediscount/logic.js` + +### Execute a contract +To execute a contract, we pass the necessary parameters including the CTO, Ergo files, the name of a contract and the json files containing request and contract state +ergorun [ctos] [ergos] --contractname [file] --contract [file] --state [file] --request [file] + +So for example we use ergorun with : +```sh +$ ergorun ./examples/volumediscount/model.cto ./examples/volumediscount/logic.ergo +--contractname org.accordproject.volumediscount.VolumeDiscount +--contract ./examples/volumediscount/contract.json +--request ./examples/volumediscount/request.json +--state ./examples/volumediscount/state.json +``` + +Here contract.json contains the following values +```json +{ + "$class": "org.accordproject.volumediscount.VolumeDiscountContract", + "parties": null, + "contractId": "cr1", + "firstVolume": 1, + "secondVolume": 10, + "firstRate": 3, + "secondRate": 2.9, + "thirdRate": 2.8 +} +``` + +Request.json contains +```json +{ + "$class": "org.accordproject.volumediscount.VolumeDiscountRequest", + "netAnnualChargeVolume": 10.4 +} +``` + +logic.ergo contains: +```ergo +namespace org.accordproject.volumediscount + +contract VolumeDiscount over VolumeDiscountContract { + // Clause for volume discount + clause volumediscount(request : VolumeDiscountRequest) : VolumeDiscountResponse { + if request.netAnnualChargeVolume < contract.firstVolume + then return VolumeDiscountResponse{ discountRate: contract.firstRate } + else if request.netAnnualChargeVolume < contract.secondVolume + then return VolumeDiscountResponse{ discountRate: contract.secondRate } + else return VolumeDiscountResponse{ discountRate: contract.thirdRate } + } +} +``` + +Here netAnnualCharge Volume equals 10.4 which is not less than firstVolume and secondVolume which are equal to 1 and 10 respectively so the logic for the volumediscount clause returns thirdRate which equals 2.8 + +``` +7:31:58 PM - info: Logging initialized. 2018-09-27T23:31:58.623Z +7:31:59 PM - info: {"response":{"discountRate":2.8,"$class":"org.accordproject.volumediscount.VolumeDiscountResponse"},"state":{"$class":"org.accordproject.cicero.contract.AccordContractState","stateId":"1"},"emit":[]} +``` + +PS D:\Users\jbambara\Github\ergo> + +## Ergo Development + +Create Template +Start with basic agreement in natural language and locate the variables +Here in the example see the bold +Volume-Based Card Acceptance Agreement [Abbreviated] +This Agreement is by and between ………..you agree to be bound by the Agreement. +Discount means an amount that we charge you for accepting the Card, which amount is: +(i) a percentage (Discount Rate) of the face amount of the Charge that you submit, or a flat per- +Transaction fee, or a combination of both; and/or +(ii) a Monthly Flat Fee (if you meet our requirements). + +Transaction Processing and Payments. ………………… less all applicable deductions, rejections, and withholdings, which include: +…………………………. + +SETTLEMENT +a) Settlement Amount. Our agent will pay you according to your payment plan, ……………………..which include: + (i) the Discount, +………………………………………….. +b) Discount. The Discount is determined according to the following table: + +| Annual Dollar Volume | Discount | +| Less than $1 million | 3.00% | +| $1 million to $10 million | 2.90% | +| Greater than $10 million | 2.80% | +Identify the request variables and contract instance variables +Codify the variables with $[{request}] or [{contract instance}] +| Annual Dollar Volume | Discount | +| Less than $[{firstVolume}] million | [{firstRate}]% | +| $[{firstVolume}] million to $[{secondVolume}] million | [{secondRate}]% | +| Greater than $[{secondVolume}] million | [{thirdRate}]% | + +Create Model +Define the model asset which contains the contract instance variables and the transaction request and response. Defines the data model for the VolumeDiscount template. This defines the structure that the parser for the template generates from input source text. See model.cto below: + namespace org.accordproject.volumediscount +import org.accordproject.cicero.contract.* from https://models.accordproject.org/cicero/contract.cto +import org.accordproject.cicero.runtime.* from https://models.accordproject.org/cicero/runtime.cto +asset VolumeDiscountContract extends AccordContract { + o Double firstVolume + o Double secondVolume + o Double firstRate + o Double secondRate + o Double thirdRate +} +transaction VolumeDiscountRequest { + o Double netAnnualChargeVolume +} +transaction VolumeDiscountResponse { + o Double discountRate +} + +Create Logic +The contract logic is accomplished by coding ERGO statements and expressions to consume the request and use contract instance variables to produce the desired response. In our example, request.netAnnualChargeVolume is tested against contract rates to produce the result. +namespace org.accordproject.volumediscount + +define the contract +contract VolumeDiscount over VolumeDiscountContract { + +define the contract clause and request : response + + clause volumediscount(request : VolumeDiscountRequest) : VolumeDiscountResponse { + +define the logic ; here we use if /then /else statement to test request parameter against contract instance variable + and return + + if request.netAnnualChargeVolume < contract.firstVolume + then return VolumeDiscountResponse{ discountRate: contract.firstRate } + else if request.netAnnualChargeVolume < contract.secondVolume + then return VolumeDiscountResponse{ discountRate: contract.secondRate } + else return VolumeDiscountResponse{ discountRate: contract.thirdRate } + } + +Ergo Language +As you have seen in this tutorial, Ergo is a domain-specific language (DSL) that captures the execution logic of legal contracts. In this simple example, you see that Ergo aims to have contracts and clauses as first-class elements of the language. To accommodate the maturation of distributed ledger implementations, Ergo will be blockchain neutral, i.e., the same contract logic can be executed either on and off chain on distributed ledger technologies like HyperLedger Fabric. Most importantly, Ergo is consistent with the Accord Protocol Template Specification. Follow the links below to learn more about +Introduction to Ergo +Ergo Language Guide +Ergo Reference Guide + + +October 12, 2018 diff --git a/docs/tutorial-playground.md b/docs/tutorial-playground.md index beb00629..914bf3af 100644 --- a/docs/tutorial-playground.md +++ b/docs/tutorial-playground.md @@ -1,271 +1,271 @@ ---- -id: tutorial-playground -title: With Template playground ---- - -This tutorial will walk you through the steps of editing a clause template in [Template Playground](https://playground.accordproject.org/). - -We start with a very simple _Late Penalty and Delivery_ Clause and gradually make it more complex, adding both legal text to it and the corresponding business logic in Ergo. - -## Initial Late Delivery Clause - -### Load the Template - -To get started, head to the `minilatedeliveryandpenalty` template in the Accord Project Template Library at [Mini Late Delivery And Penalty](https://templates.accordproject.org/minilatedeliveryandpenalty@0.6.0.html) and click the "Open In Template Playground" button. - -![Advanced-Late-1](assets/advanced/late1.png) - -Begin by inspecting the `README` and `package.json` tabs within the `Metadata` section. Feel free to change the name of the template to one you like. - -### The Contract Text - -Then click on the `Text` Section on the left, which should show a `Grammar` tab, for the the natural language of the template. - -![Advanced-Late-2](assets/advanced/late2.png) - -When the text in the `Grammar` tab is in sync with the text in the `Sample` tab, this means the sample is a valid with respect to the grammar, and data is extracted, showing in `Contract Data` tab. The contract data is represented using the JSON format and contains the value of the variables declared in the contract template. For instance, the value for the `buyer` variable is `Betty Buyer`, highlighted in red: - -![Advanced-Late-3](assets/advanced/late3.png) - -Changes to the variables in the `Sample` are reflected in the `Contract Data` tab in real time, and vice versa. For instance, change `Betty Buyer` to a different name in the contract text to see the `partyId` change in the contract data. - -:::note -The JSON data `resource:org.accordproject.party.Party#Betty%20Buyer` indicate that the value is a relationship of type `Party` whose identifier is `Betty Buyer`. Consult the [Concerto Guide](model-relationships) for more details on modeling relationships. -::: - -If you edit part of the text which is not a variable in the template, this results in an error when parsing the `Sample`. The error will be shown in red in the status bar at the bottom of the page. For instance, the following image shows the parsing error obtained when changing the word `delayed` to the word `timely` in the contract text. - -![Advanced-Late-4](assets/advanced/late4.png) - -This is because the `Sample` relies on the `Grammar` text as a source of truth. This mechanism ensures that the actual contract always reflects the template, and remains faithful to the original legal text. You can, however, edit the `Grammar` itself to change the legal text. - -Revert your changes, changing the word `timely` back to the original word `delayed` and the parsing error will disappear. - -### The Model - -Moving along to the `Model` section, you will find the data model for the template variables (the `MiniLateDeliveryClause` type), as well as for the requests (the `LateRequest` type) and response (the `LateResponse` type) for the late delivery and penalty clause. - -![Advanced-Late-5](assets/advanced/late5.png) - -Note that a `namespace` is declared at the beginning of the file for the model, and that several existing models are being imported (using e.g., `import org.accordproject.contract.*`). Those imports are needed to access the definition for several types used in the model: -- `Clause` which is a generic type for all Accord Project clause templates, and is defined in the `org.accordproject.contract` namespace; -- `Party` which is a generic type for all Accord Project parties, and is defined in the `org.accordproject.party` namespace; -- `Request` and `Response` which are generic types for responses and requests, and are defined in the `org.accordproject.runtime` namespace; -- `Duration` which is defined in the `org.accordproject.time` namespace. - -### The Logic - -The final part of the template is the `Ergo` tab of the `Logic` section, which describes the business logic. - -![Advanced-Late-6](assets/advanced/late6.png) - -Thanks to the `namespace` at the beginning of this file, the Ergo engine can know the definition for the `MiniLateDeliveryClause`, as well as the `LateRequest`, and `LateResponse` types defined in the `Model` tab. - -To test the template execution, go to the `Request` tab in the `Logic` section. It should be already populated with a valid request. Press the `Trigger` button to trigger the clause. - -![Advanced-Late-7](assets/advanced/late7.png) - -Since the value of the `deliveredAt` parameter in the request is after the value of the `agreedDelivery` parameter in the request, this should return a new response which includes the calculated penalty. - -Changing the date for the `deliveredAt` parameter in the request and triggering the contract again will result in a different penalty. - -![Advanced-Late-8](assets/advanced/late8.png) - -Note that the clause will return an error if it is called for a timely delivery. - -![Advanced-Late-9](assets/advanced/late9.png) - -## Add a Penalty Cap - -We can now start building a more advanced clause. Let us first take a moment to notice that there is no limitation to the penalty resulting from a late delivery. Trigger the contract using the following request in the `Request` tab in `Logic`: -```json -{ - "$class": "org.accordproject.minilatedeliveryandpenalty.LateRequest", - "agreedDelivery": "2019-04-10T12:00:00-05:00", - "deliveredAt": "2019-04-20T03:24:00-05:00", - "goodsValue": 200 -} -``` -The penalty should be rather low. Now send this other request: -```json -{ - "$class": "org.accordproject.minilatedeliveryandpenalty.LateRequest", - "agreedDelivery": "2005-04-01T12:00:00-05:00", - "deliveredAt": "2019-04-20T03:24:00-05:00", - "goodsValue": 200 -} -``` -Notice that the penalty is now quite a large value. It is not unusual to cap a penalty to a maximum amount. Let us now look at how to change the template to add such a cap based on a percentage of the total value of the delivered goods. - -### Update the Legal Text - -To implement this, we first go to the `Grammar` tab in the `Text` section and add a sentence indicating: `The total amount of penalty shall not, however, exceed {{capPercentage}}% of the total value of the delayed goods.` - -For convenience, you can copy-paste the new template text from here: -```tem -Late Delivery and Penalty. - -In case of delayed delivery of Goods, {{seller}} shall pay to -{{buyer}} a penalty amounting to {{penaltyPercentage}}% of the total -value of the Goods for every {{penaltyDuration}} of delay. The total -amount of penalty shall not, however, exceed {{capPercentage}}% of the -total value of the delayed goods. If the delay is more than -{{maximumDelay}}, the Buyer is entitled to terminate this Contract. - -``` -This should immediately result in an error when parsing the contract text: - -![Advanced-Late-10](assets/advanced/late10.png) - -As explained in the error message, this is because the new template text uses a variable `capPercentage` which has not been declared in the model. - -### Update the Model - -To define this new variable, go to the `Model` tab, and change the `MiniLateDeliveryClause` type to include `o Double capPercentage`. - -![Advanced-Late-11](assets/advanced/late11.png) - -For convenience, you can copy-paste the new `MiniLateDeliveryClause` type from here: -```ergo -asset MiniLateDeliveryClause extends Clause { - --> Party buyer // Party to the contract (buyer) - --> Party seller // Party to the contract (seller) - o Duration penaltyDuration // Length of time resulting in penalty - o Double penaltyPercentage // Penalty percentage - o Double capPercentage // Maximum penalty percentage - o Duration maximumDelay // Maximum delay before termination -} -``` - -This results in a new error, this time on the sample contract: - -![Advanced-Late-12](assets/advanced/late12.png) - -To fix it, we need to add that same line we added to the template, replacing the `capPercentage` by a value in the `Test Contract`: `The total amount of penalty shall not, however, exceed 52% of the total value of the delayed goods.` - -For convenience, you can copy-paste the new test contract from here: -```md -Late Delivery and Penalty. - -In case of delayed delivery of Goods, "Steve Seller" shall pay to -"Betty Buyer" a penalty amounting to 10.5% of the total -value of the Goods for every 2 days of delay. The total -amount of penalty shall not, however, exceed 52% of the -total value of the delayed goods. If the delay is more than -15 days, the Buyer is entitled to terminate this Contract. - -``` - -Great, now the edited template should have no more errors, and the contract data should now include the value for the new `capPercentage` variable. - -![Advanced-Late-13](assets/advanced/late13.png) - -Note that the `Current Template` Tab indicates that the template has been changed. - -### Update the Logic - -At this point, executing the logic will still result in large penalties. This is because the logic does not take advantage of the new `capPercentage` variable. Edit the `logic.ergo` code to do so. After step `// 2. Penalty formula` in the logic, apply the penalty cap by adding some logic as follows: -```ergo - // 3. Capped Penalty - let cap = contract.capPercentage / 100.0 * request.goodsValue; - - let cappedPenalty = - if penalty > cap - then cap - else penalty; - -``` -Do not forget to also change the value of the penalty in the returned `LateResponse` to use the new variable `cappedPenalty`: -```ergo - // 5. Return the response - return LateResponse{ - penalty: cappedPenalty, - buyerMayTerminate: termination - } -``` -The logic should now look as follows: - -![Advanced-Late-14](assets/advanced/late14.png) - -### Run the new Logic - -As a final test of the new template, you should try again to run the contract with a long delay in delivery. This should now result in a much smaller penalty, which is capped to 52% of the total value of the goods, or 104 USD. - -![Advanced-Late-15](assets/advanced/late15.png) - -:::tip -A full version of the template after those changes have been applied can be found as the [Mini Late Delivery And Penalty Capped](https://templates.accordproject.org/minilatedeliveryandpenalty-capped@0.6.0.html) in the Template Library. -::: - -## Emit a Payment Obligation. - -As a final extension to this template, we can modify it to emit a Payment Obligation. This first requires us to switch from a Clause template to a Contract template. - -### Switch to a Contract Template - -The first place to change is in the metadata for the template. This can be done easily with the `full contract` button in the `Current Template` tab. This will immediately result in an error indicating that the model does not contain an `Contract` type. - -![Advanced-Late-16](assets/advanced/late16.png) - -### Update the Model - -To fix this, change the model to reflect that we are now editing a contract template, and change the type `AccordClause` to `AccordContract` in the type definition for the template variables: -```ergo -asset MiniLateDeliveryContract extends Contract { - --> Party buyer // Party to the contract (buyer) - --> Party seller // Party to the contract (seller) - o Duration penaltyDuration // Length of time resulting in penalty - o Double penaltyPercentage // Penalty percentage - o Double capPercentage // Maximum penalty percentage - o Duration maximumDelay // Maximum delay before termination -} -``` - -The next error is in the logic, since it still uses the old `MiniLateDeliveryClause` type which does not exist anymore. - -### Update the Logic - -The `Logic` error that occurs here is: -```bash -Compilation error (at file lib/logic.ergo line 19 col 31). Cannot find type with name 'MiniLateDeliveryClause' -contract MiniLateDelivery over MiniLateDeliveryClause { - ^^^^^^^^^^^^^^^^^^^^^^ -``` -Update the logic to use the the new `MiniLateDeliveryContract` type instead, as follows: -```ergo -contract MiniLateDelivery over MiniLateDeliveryContract { -``` - -The template should now be without errors. - -### Add a Payment Obligation - -Our final task is to emit a `PaymentObligation` to indicate that the buyer should pay the seller in the amount of the calculated penalty. - -To do so, first import a couple of standard models: for the Cicero's [runtime model](https://models.accordproject.org/cicero/runtime.html) (which contains the definition of a `PaymentObligation`), and for the Accord Project's [money model](https://models.accordproject.org/money.html) (which contains the definition of a `MonetaryAmount`). The `import` statements at the top of your logic should look as follows: -```ergo -import org.accordproject.time.* -import org.accordproject.cicero.runtime.* -import org.accordproject.money.MonetaryAmount - -``` - -Lastly, add a new step between steps `// 4.` and `// 5.` in the logic to emit a payment obligation in USD: -```ergo - emit PaymentObligation{ - contract: contract, - promisor: some(contract.seller), - promisee: some(contract.buyer), - deadline: none, - amount: MonetaryAmount{ doubleValue: cappedPenalty, currencyCode: USD }, - description: contract.seller.partyId ++ " should pay penalty amount to " ++ contract.buyer.partyId - }; - -``` -That's it! You can observe in the `Request` tab that an `Obligation` is now being emitted. Try out adjusting values and continuing to send requests and getting responses and obligations. - -![Advanced-Late-17](assets/advanced/late17.png) - -:::tip -A full version of the template after those changes have been applied can be found as the [Mini-Late Delivery and Penalty Payment](https://templates.accordproject.org/minilatedeliveryandpenalty-payment@0.6.0.html) in the Template Library. -::: +--- +id: tutorial-playground +title: With Template playground +--- + +This tutorial will walk you through the steps of editing a clause template in [Template Playground](https://playground.accordproject.org/). + +We start with a very simple _Late Penalty and Delivery_ Clause and gradually make it more complex, adding both legal text to it and the corresponding business logic in Ergo. + +## Initial Late Delivery Clause + +### Load the Template + +To get started, head to the `minilatedeliveryandpenalty` template in the Accord Project Template Library at [Mini Late Delivery And Penalty](https://templates.accordproject.org/minilatedeliveryandpenalty@0.6.0.html) and click the "Open In Template Playground" button. + +![Advanced-Late-1](assets/advanced/late1.png) + +Begin by inspecting the `README` and `package.json` tabs within the `Metadata` section. Feel free to change the name of the template to one you like. + +### The Contract Text + +Then click on the `Text` Section on the left, which should show a `Grammar` tab, for the the natural language of the template. + +![Advanced-Late-2](assets/advanced/late2.png) + +When the text in the `Grammar` tab is in sync with the text in the `Sample` tab, this means the sample is a valid with respect to the grammar, and data is extracted, showing in `Contract Data` tab. The contract data is represented using the JSON format and contains the value of the variables declared in the contract template. For instance, the value for the `buyer` variable is `Betty Buyer`, highlighted in red: + +![Advanced-Late-3](assets/advanced/late3.png) + +Changes to the variables in the `Sample` are reflected in the `Contract Data` tab in real time, and vice versa. For instance, change `Betty Buyer` to a different name in the contract text to see the `partyId` change in the contract data. + +:::note +The JSON data `resource:org.accordproject.party.Party#Betty%20Buyer` indicate that the value is a relationship of type `Party` whose identifier is `Betty Buyer`. Consult the [Concerto Guide](model-relationships) for more details on modeling relationships. +::: + +If you edit part of the text which is not a variable in the template, this results in an error when parsing the `Sample`. The error will be shown in red in the status bar at the bottom of the page. For instance, the following image shows the parsing error obtained when changing the word `delayed` to the word `timely` in the contract text. + +![Advanced-Late-4](assets/advanced/late4.png) + +This is because the `Sample` relies on the `Grammar` text as a source of truth. This mechanism ensures that the actual contract always reflects the template, and remains faithful to the original legal text. You can, however, edit the `Grammar` itself to change the legal text. + +Revert your changes, changing the word `timely` back to the original word `delayed` and the parsing error will disappear. + +### The Model + +Moving along to the `Model` section, you will find the data model for the template variables (the `MiniLateDeliveryClause` type), as well as for the requests (the `LateRequest` type) and response (the `LateResponse` type) for the late delivery and penalty clause. + +![Advanced-Late-5](assets/advanced/late5.png) + +Note that a `namespace` is declared at the beginning of the file for the model, and that several existing models are being imported (using e.g., `import org.accordproject.contract.*`). Those imports are needed to access the definition for several types used in the model: +- `Clause` which is a generic type for all Accord Project clause templates, and is defined in the `org.accordproject.contract` namespace; +- `Party` which is a generic type for all Accord Project parties, and is defined in the `org.accordproject.party` namespace; +- `Request` and `Response` which are generic types for responses and requests, and are defined in the `org.accordproject.runtime` namespace; +- `Duration` which is defined in the `org.accordproject.time` namespace. + +### The Logic + +The final part of the template is the `Ergo` tab of the `Logic` section, which describes the business logic. + +![Advanced-Late-6](assets/advanced/late6.png) + +Thanks to the `namespace` at the beginning of this file, the Ergo engine can know the definition for the `MiniLateDeliveryClause`, as well as the `LateRequest`, and `LateResponse` types defined in the `Model` tab. + +To test the template execution, go to the `Request` tab in the `Logic` section. It should be already populated with a valid request. Press the `Trigger` button to trigger the clause. + +![Advanced-Late-7](assets/advanced/late7.png) + +Since the value of the `deliveredAt` parameter in the request is after the value of the `agreedDelivery` parameter in the request, this should return a new response which includes the calculated penalty. + +Changing the date for the `deliveredAt` parameter in the request and triggering the contract again will result in a different penalty. + +![Advanced-Late-8](assets/advanced/late8.png) + +Note that the clause will return an error if it is called for a timely delivery. + +![Advanced-Late-9](assets/advanced/late9.png) + +## Add a Penalty Cap + +We can now start building a more advanced clause. Let us first take a moment to notice that there is no limitation to the penalty resulting from a late delivery. Trigger the contract using the following request in the `Request` tab in `Logic`: +```json +{ + "$class": "org.accordproject.minilatedeliveryandpenalty.LateRequest", + "agreedDelivery": "2019-04-10T12:00:00-05:00", + "deliveredAt": "2019-04-20T03:24:00-05:00", + "goodsValue": 200 +} +``` +The penalty should be rather low. Now send this other request: +```json +{ + "$class": "org.accordproject.minilatedeliveryandpenalty.LateRequest", + "agreedDelivery": "2005-04-01T12:00:00-05:00", + "deliveredAt": "2019-04-20T03:24:00-05:00", + "goodsValue": 200 +} +``` +Notice that the penalty is now quite a large value. It is not unusual to cap a penalty to a maximum amount. Let us now look at how to change the template to add such a cap based on a percentage of the total value of the delivered goods. + +### Update the Legal Text + +To implement this, we first go to the `Grammar` tab in the `Text` section and add a sentence indicating: `The total amount of penalty shall not, however, exceed {{capPercentage}}% of the total value of the delayed goods.` + +For convenience, you can copy-paste the new template text from here: +```tem +Late Delivery and Penalty. + +In case of delayed delivery of Goods, {{seller}} shall pay to +{{buyer}} a penalty amounting to {{penaltyPercentage}}% of the total +value of the Goods for every {{penaltyDuration}} of delay. The total +amount of penalty shall not, however, exceed {{capPercentage}}% of the +total value of the delayed goods. If the delay is more than +{{maximumDelay}}, the Buyer is entitled to terminate this Contract. + +``` +This should immediately result in an error when parsing the contract text: + +![Advanced-Late-10](assets/advanced/late10.png) + +As explained in the error message, this is because the new template text uses a variable `capPercentage` which has not been declared in the model. + +### Update the Model + +To define this new variable, go to the `Model` tab, and change the `MiniLateDeliveryClause` type to include `o Double capPercentage`. + +![Advanced-Late-11](assets/advanced/late11.png) + +For convenience, you can copy-paste the new `MiniLateDeliveryClause` type from here: +```ergo +asset MiniLateDeliveryClause extends Clause { + --> Party buyer // Party to the contract (buyer) + --> Party seller // Party to the contract (seller) + o Duration penaltyDuration // Length of time resulting in penalty + o Double penaltyPercentage // Penalty percentage + o Double capPercentage // Maximum penalty percentage + o Duration maximumDelay // Maximum delay before termination +} +``` + +This results in a new error, this time on the sample contract: + +![Advanced-Late-12](assets/advanced/late12.png) + +To fix it, we need to add that same line we added to the template, replacing the `capPercentage` by a value in the `Test Contract`: `The total amount of penalty shall not, however, exceed 52% of the total value of the delayed goods.` + +For convenience, you can copy-paste the new test contract from here: +```md +Late Delivery and Penalty. + +In case of delayed delivery of Goods, "Steve Seller" shall pay to +"Betty Buyer" a penalty amounting to 10.5% of the total +value of the Goods for every 2 days of delay. The total +amount of penalty shall not, however, exceed 52% of the +total value of the delayed goods. If the delay is more than +15 days, the Buyer is entitled to terminate this Contract. + +``` + +Great, now the edited template should have no more errors, and the contract data should now include the value for the new `capPercentage` variable. + +![Advanced-Late-13](assets/advanced/late13.png) + +Note that the `Current Template` Tab indicates that the template has been changed. + +### Update the Logic + +At this point, executing the logic will still result in large penalties. This is because the logic does not take advantage of the new `capPercentage` variable. Edit the `logic.ergo` code to do so. After step `// 2. Penalty formula` in the logic, apply the penalty cap by adding some logic as follows: +```ergo + // 3. Capped Penalty + let cap = contract.capPercentage / 100.0 * request.goodsValue; + + let cappedPenalty = + if penalty > cap + then cap + else penalty; + +``` +Do not forget to also change the value of the penalty in the returned `LateResponse` to use the new variable `cappedPenalty`: +```ergo + // 5. Return the response + return LateResponse{ + penalty: cappedPenalty, + buyerMayTerminate: termination + } +``` +The logic should now look as follows: + +![Advanced-Late-14](assets/advanced/late14.png) + +### Run the new Logic + +As a final test of the new template, you should try again to run the contract with a long delay in delivery. This should now result in a much smaller penalty, which is capped to 52% of the total value of the goods, or 104 USD. + +![Advanced-Late-15](assets/advanced/late15.png) + +:::tip +A full version of the template after those changes have been applied can be found as the [Mini Late Delivery And Penalty Capped](https://templates.accordproject.org/minilatedeliveryandpenalty-capped@0.6.0.html) in the Template Library. +::: + +## Emit a Payment Obligation. + +As a final extension to this template, we can modify it to emit a Payment Obligation. This first requires us to switch from a Clause template to a Contract template. + +### Switch to a Contract Template + +The first place to change is in the metadata for the template. This can be done easily with the `full contract` button in the `Current Template` tab. This will immediately result in an error indicating that the model does not contain an `Contract` type. + +![Advanced-Late-16](assets/advanced/late16.png) + +### Update the Model + +To fix this, change the model to reflect that we are now editing a contract template, and change the type `AccordClause` to `AccordContract` in the type definition for the template variables: +```ergo +asset MiniLateDeliveryContract extends Contract { + --> Party buyer // Party to the contract (buyer) + --> Party seller // Party to the contract (seller) + o Duration penaltyDuration // Length of time resulting in penalty + o Double penaltyPercentage // Penalty percentage + o Double capPercentage // Maximum penalty percentage + o Duration maximumDelay // Maximum delay before termination +} +``` + +The next error is in the logic, since it still uses the old `MiniLateDeliveryClause` type which does not exist anymore. + +### Update the Logic + +The `Logic` error that occurs here is: +```bash +Compilation error (at file lib/logic.ergo line 19 col 31). Cannot find type with name 'MiniLateDeliveryClause' +contract MiniLateDelivery over MiniLateDeliveryClause { + ^^^^^^^^^^^^^^^^^^^^^^ +``` +Update the logic to use the the new `MiniLateDeliveryContract` type instead, as follows: +```ergo +contract MiniLateDelivery over MiniLateDeliveryContract { +``` + +The template should now be without errors. + +### Add a Payment Obligation + +Our final task is to emit a `PaymentObligation` to indicate that the buyer should pay the seller in the amount of the calculated penalty. + +To do so, first import a couple of standard models: for the Cicero's [runtime model](https://models.accordproject.org/cicero/runtime.html) (which contains the definition of a `PaymentObligation`), and for the Accord Project's [money model](https://models.accordproject.org/money.html) (which contains the definition of a `MonetaryAmount`). The `import` statements at the top of your logic should look as follows: +```ergo +import org.accordproject.time.* +import org.accordproject.cicero.runtime.* +import org.accordproject.money.MonetaryAmount + +``` + +Lastly, add a new step between steps `// 4.` and `// 5.` in the logic to emit a payment obligation in USD: +```ergo + emit PaymentObligation{ + contract: contract, + promisor: some(contract.seller), + promisee: some(contract.buyer), + deadline: none, + amount: MonetaryAmount{ doubleValue: cappedPenalty, currencyCode: USD }, + description: contract.seller.partyId ++ " should pay penalty amount to " ++ contract.buyer.partyId + }; + +``` +That's it! You can observe in the `Request` tab that an `Obligation` is now being emitted. Try out adjusting values and continuing to send requests and getting responses and obligations. + +![Advanced-Late-17](assets/advanced/late17.png) + +:::tip +A full version of the template after those changes have been applied can be found as the [Mini-Late Delivery and Penalty Payment](https://templates.accordproject.org/minilatedeliveryandpenalty-payment@0.6.0.html) in the Template Library. +::: From b6ce0de4ba0bd5ef302b3dd63a5a0e47aadaf42f Mon Sep 17 00:00:00 2001 From: tbrooke Date: Wed, 30 Jul 2025 08:24:13 -0400 Subject: [PATCH 5/6] change Template Studio to Template Playground Signed-off-by: tbrooke --- docs/accordproject-tour.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/accordproject-tour.md b/docs/accordproject-tour.md index f10eb33a..bfe53efd 100644 --- a/docs/accordproject-tour.md +++ b/docs/accordproject-tour.md @@ -3,7 +3,7 @@ id: accordproject-tour title: Online Tour --- -To get better acquainted with Accord Project templates, the easiest way is through the online [Template Studio](https://studio.accordproject.org) editor. +To get better acquainted with Accord Project templates, the easiest way is through the online [Template Playground](https://playground.accordproject.org) editor. :::tip You can open template playground from anywhere in this documentation by clicking the [Try Online!]( Date: Wed, 30 Jul 2025 09:02:19 -0400 Subject: [PATCH 6/6] Commented out Studio video Signed-off-by: tbrooke --- docs/accordproject-tour.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/accordproject-tour.md b/docs/accordproject-tour.md index bfe53efd..7f3b87e4 100644 --- a/docs/accordproject-tour.md +++ b/docs/accordproject-tour.md @@ -10,7 +10,7 @@ You can open template playground from anywhere in this documentation by clicking ::: The following video offers a tour of Template playground and an introduction to the key concepts behind the Accord Project technology. - +