diff --git a/docs/accordproject-faq.md b/docs/accordproject-faq.md index d93d4a3d..9acb0b53 100644 --- a/docs/accordproject-faq.md +++ b/docs/accordproject-faq.md @@ -50,9 +50,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/docs/accordproject-template.md b/docs/accordproject-template.md index fb7c2543..4c7f1285 100644 --- a/docs/accordproject-template.md +++ b/docs/accordproject-template.md @@ -205,7 +205,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](https://playground.accordproject.org/) 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/docs/accordproject-tour.md b/docs/accordproject-tour.md deleted file mode 100644 index cd1bea20..00000000 --- a/docs/accordproject-tour.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -id: accordproject-tour -title: Online Tour ---- - -To get an 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. -::: - -The following video offers a tour of Template Studio and an introduction to the key concepts behind the Accord Project technology. - - - -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 -- **03:51** : Helloworld template tutorial start -- **04:48** : Template Studio - Metadata -- **06:56** : Template Studio - 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 - - **13:17** : Explanation about request types / response types -- **14:44** : Template Studio - Logic - Test Execution (request, response) - - **15:57** : Test Execution - contract state - - **16:49** : Test Execution - obligations -- **18:20** : Wrap-up - diff --git a/docs/accordproject.md b/docs/accordproject.md index fa7e679e..4144e313 100644 --- a/docs/accordproject.md +++ b/docs/accordproject.md @@ -45,7 +45,7 @@ There is a welcoming community on Discord that is eager to help. [Join our Commu ## About this documentation -If you are new to Accord Project, you may want to first read about the notion of [Smart Legal Contracts](accordproject-slc.md) and about [Accord Project Templates](accordproject-template.md). We also recommend taking the [Online Tour](accordproject-tour.md). +If you are new to Accord Project, you may want to first read about the notion of [Smart Legal Contracts](accordproject-slc.md) and about [Accord Project Templates](accordproject-template.md). To start using Accord Project templates, follow the [Install Cicero](https://docs.accordproject.org/docs/next/started-installation.html) instructions in the _Getting Started_ Section of the documentation. diff --git a/docs/started-resources.md b/docs/started-resources.md index 2e19e4a8..1971f067 100644 --- a/docs/started-resources.md +++ b/docs/started-resources.md @@ -23,7 +23,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/docs/tutorial-studio.md b/docs/tutorial-studio.md deleted file mode 100644 index 47386834..00000000 --- a/docs/tutorial-studio.md +++ /dev/null @@ -1,271 +0,0 @@ ---- -id: tutorial-studio -title: With Template Studio ---- - -This tutorial will walk you through the steps of editing a clause template in [Template Studio](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. - -## 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 Studio" button. - - - -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. - - - -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: - - - -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. - - - -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. - - - -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. - - - -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. - - - -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. - - - -Note that the clause will return an error if it is called for a timely delivery. - - - -## 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: - - - -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`. - - - -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: - - - -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. - - - -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: - - - -### 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. - - - -:::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. - - - -### 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. - - - -:::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. -::: diff --git a/website/i18n/en.json b/website/i18n/en.json index 7cddeebf..9d429930 100644 --- a/website/i18n/en.json +++ b/website/i18n/en.json @@ -14,9 +14,6 @@ "accordproject-template": { "title": "Accord Project Templates" }, - "accordproject-tour": { - "title": "Online Tour" - }, "accordproject": { "title": "Overview" }, @@ -137,9 +134,6 @@ "tutorial-nodejs": { "title": "With Node.js" }, - "tutorial-studio": { - "title": "With Template Studio" - }, "tutorial-templates": { "title": "Templates Deep Dive" }, diff --git a/website/package-lock.json b/website/package-lock.json index 109007cb..9317a711 100644 --- a/website/package-lock.json +++ b/website/package-lock.json @@ -4,7 +4,6 @@ "requires": true, "packages": { "": { - "name": "website", "license": "Apache-2.0", "dependencies": { "axios": "^0.21.2", diff --git a/website/pages/en/index.js b/website/pages/en/index.js index afb1623b..d9588cbd 100755 --- a/website/pages/en/index.js +++ b/website/pages/en/index.js @@ -204,7 +204,7 @@ const TryOut = props => ( {[ { content: - '