accordproject / ergo Goto Github PK

Since adding all of the ergo npm packages to the @accordproject scope, the documentation is now out of date.

For example, occurences of npm install ergo-cli -g should be replaced with npm install @accordproject/ergo-cli -g

We should have a way to embed Ergo in the browser. This would be a better way to implement #5 as well.

We should have a documentation for the precedence of expressions/operators in the language. See the one from Java for example: https://docs.oracle.com/javase/tutorial/java/nutsandbolts/operators.html

Initial work using sexpressions to show case the intermediate calculus aren't tested or used anymore. They should probably be removed now that there is a full parser for Ergo.

It might be cleaner/better to introduce a distinction between statements and expressions to more clearly isolate the part of the Ergo logic that can affect state (e.g., change contract state, return an error, emit a transaction).

This could also facilitate code generation by more clearly isolating the purely functional part from the state change part of the logic.

Here is a possible beginning for a statement grammar:

statement ::=
| statement ; statement   // sequence
| define variable Var (: Type)? := expression; statement
| if expression then statement (else statement)?
| enforce expression (else statement)?; statement
| return expression
| reject expression
| emit expression
| set state expression
...

It might be useful to have a tuple type in Ergo. The typical use case is for a function or a clause that needs to return multiple values. See the corresponding issue in accordproject/template-archive#37

We should provide a full formal semantics for Ergo (maybe in a pretty-big-step style).

The current method name is ContractName_ClauseName but this is unnecessary inside a class and could be replaced by ClauseName.

It would be great to be able to match values against types. This could be a new operator in the language e.g., e instanceof T or e is of type T.

This could also be used for the underlying semantics of define variable x : T := e.

I believe instanceof can be supported as an operator and compiled to an underlying combination of data-type inference and sub typing (See querycert/qcert#95).

Additionally, this might allow us to consolidate the pattern matching expression, which currently only works for either class names or values, and from there to generalize the type dispatch implemented for #15

We are currently using:
if e1 { e2 } else { e3 } and match e1 with e2 : e3 ... otherwise en

We might want to consolidate and remove the curly braces in the conditional as follows:
if e1 then e2 else e3 and match e1 with e2 then ... else en

This also removes one overloading for the : character (see #28).

It would be useful to allow record values and types (similar to JSON objects). Those could also be interpreted as anonymous CTO concept. Those would most naturally be written in a way similar to JSON as:

{ name : "John", age : 32 }

Note that in contract concepts are created with their concept names as follows:

new Person{ name : "John", age : 32 }

There are some issues in how numeric values are being handled. The compiler doesn't produce code which properly distinguish operations on Double and operations on Integer(or Long).

The documentation should include some example legal text to help illustrate the Ergo Syntax.
Particularly for:

• Conditional expressions
• Enforce expressions
• Match expressions

Currently, the Jura compiler does not import CTO model files. Those are needed for: syntactic sugar (e.g., new Asset{ value1, value2 } instead of new Asset{ field1: value1, field2: value2 }, type checking, optimization, etc.

The character : is used in multiple places at the moment (for indicating a type in a function signature or variable declaration, for object/record construction, and in the match expression. We could use then .. else in the match expression to limit the amount of overloading for the : character.

The Jura documentation lists all CTO datatypes should be available. Those include:

Boolean
String
Double
Long
Integer
DateTime

For the GitHub Pages documentation for Ergo, I want a table of contents to help me navigate the documentation.

Some review/consolidation of the namespace handling in Ergo should happen. The top-level package declaration indicates a namespace for the given Ergo file. The namespace needs to be properly taken into account in type declarations, function/clause calls, etc.

The Ergo language should be validated against the existing Cicero templates (https://github.com/accordproject/cicero-template-library):

• acceptance-of-delivery
• car-rental-tr
• copyright-license
• demandforecast
• eat-apples
• fragile-goods
• helloworld
• helloworldstate
• installment-sale
• ip-payment
• latedeliveryandpenalty
• one-time-payment
• one-time-payment-tr
• payment-upon-delivery
• perishable-goods
• promissory-note
• saft
• safte
• sales-contract-ru
• servicelevelaggreement
• supplyagreement
• supplyagreement-perishable-goods
• volumediscount

It might be necessary/cleaner to instantiate the Q*cert modules for code generation before they are used in Ergo. This would freeze foreign types (e.g., for date/time) which means constructing type models is more natural. This concretely means:

• Split the Compiler directory into pre-Jura Backend and post-Ergo ErgoCompiler parts
• Import the Backend instead of Qcert in the Ergo part of the code
• Re-factor the built-in operators, CTO to model translation, etc to rely on the instantiated backend compiler
• Fix up of backend module types and definitions so it results in cleaner extracted code

The world seems united in its dislike of guard as a keyword. Also now that conditional and match statements do not use curly braces, the guard expression should avoid those as well. A possible alternative to:
guard e1 else { e2 }; and guard e1;
might be:
ensure e1 else e2; and ensure e1;

We should have documentation for the language, this should include: compiler documentation, programming model, syntax/grammar documentation, expression language, semantics, typing constraints.

The list of reserved words (language used by the language such as contract, function, etc that can't be identifiers) should be documented.

Ergo needs to be able to access/create relationships between concepts (relationships in the sense of the CTO). The acceptance of delivery template provides a simple example of that.

The jura CLI uses it's own execution code. We need to test the generated JavaScript and possibly adjust the code-generation so it can run from within Cicero.

Type name hierarchy is not yet handled properly. This is relevant for code generation, the reference interpreter, and of course for type checking.

Requires some of the following steps:

• Import of CTO files (See #9)
• Namespace resolution (See #18)
• Uniform handling of CTOs and type declaration in module (done in PR #234)
• Extract type hierarchy from ergo modules after namespace resolution (See #330)
• Pass type hierarchy to backend compiler calls
• Add code-generation for type hierarchy

We need some initial support for editing, syntax highlighting, etc.

Currently, clauses can use the built-in variable this to access clause data obtained from the template. This probably does not scale for whole contract logic where one might want to also have data from the contract as well. We might want to replace this with clause and contract to make that distinction.

Comparing original JS latedeliveryandpenalty sample with compiled JS from Ergo I see the following difference.

JS sample

/**
 * Execute the smart clause
 * @param {Context} context - the Accord Project context
 * @param {io.clause.latedeliveryandpenalty.LateDeliveryAndPenaltyRequest} context.request - the incoming request
 * @param {io.clause.latedeliveryandpenalty.LateDeliveryAndPenaltyResponse} context.response - the response
 * @AccordClauseLogic
 */

Compiled Jura

/**
 * Execute the smart clause
 * @param {Context} context - the Accord Project context
 * @param {Request} context.request - the incoming request
 * @param {Response} context.response - the response
 * @AccordClauseLogic
 */

I suspect that the missing namespaces are related to #18 , but the type names also seem to be wrong.

There should be a way to execute Ergo contracts without full compilation to get the "official" semantics.

Currently each package has sets of Jura tests in ./test/data. There is a lot of duplication, which should be avoided, maybe by each package linking to a single top-level directory.

Ergo should allow for creations of enum values. This relies on the ability to read/import CTO files.

Currently CI with Travis only tests Jura after extraction to JavaScript. We should have a separate build for testing compilation of the Jura compiler from its Coq/OCaml source code.

See : https://github.com/coq/coq/releases/tag/V8.8.0

It would be better to provide independent executables for the compiler and the CLI. The CLI might be possibly replaced by a REPL or that might be yet another executable. (See also #25).

One of the benefit of having the compiler separate is that it could include more compilation options, distinct compilation targets down the road, etc.

This might also serve to address #13

Notably:

• Parsing errors should be reported with a reference to the file rather than a "code dump"
• Compilation errors should be reported with a more useful message.
• Compilation errors should not be lost when calling execute.

We should run lint, jsdoc, etc on the Jura code.

The code-generation should be extended to include contract state change.

The Ergo runtime is a patched-up version of the Q*cert one. It is composed of vanilla JavaScript functions without module layout for node consumption. We should improve upon this in several ways:

• Automate the production of the runtime from Q*cert itself so changes/fixes there are propagated to Ergo automatically
• Allow the runtime generation to be parameterized by foreign type libraries (e.g., various support for dateTime)
• Generalize the runtime generation so it works for both browser and node

We need a type checker for Ergo and/or the Ergo Calculus. It should be based on the CTOs being imported in the Ergo contracts, it should provide correctness guarantees, it should provide useful information to the editor, it should return useful errors to the Ergo developer.

For readability we should use or instead of || and and instead of &&.

We should provide a read-eval-print-loop for Ergo. This is useful for learning the language.

The command-line interface for ergoc and ergoc.native should be aligned. Also calling the compiler without options should print out the help (identical to --help).

It would be useful to generate a readable documentation of the Jura language specification/mechanization. https://github.com/xavierleroy/coq2html is a very good candidate for this.

Currently types are only declared in CTO files and must be imported. We should allow types directly declared inside Jura.

Currently, execution for clauses requires the user to specify the contract and clause. It would be useful to allow execution to be driven by the type of the incoming transaction (typically the clause request). The execution could match the incoming transaction type against the type signature of clauses.

This is also a useful item for integration with Cicero (#8), since Cicero already uses a form of dispatch.

We should have automated testing for Jura contract compilation and execution.

Test issue

Inline expansion is the main source of compiler error (e.g., calling a function that isn't in scope or hasn't been declared). It would make the compiler code simpler and easier to debug if it was performed as a first step before translation to calculus.

There should be a way to try/learn/experiment with Ergo online (using a kind of a playground).