Document format for Accord Project contracts

[jeromesimeon]

[Inspired by @pkel]

Should we have a document format for accord project smart legal contracts?

The idea would be to have a file e.g., myAgreement.sdf file which encapsulate everything of your smart legal contract instance (rather than .cta for a template).

• It could be explained as a new document format (like a .pdf) to users, except that you can package and run contract logic on that document.
• .sdf stands for smart document format.
• .sdf files can be loaded in AP contract editor and the variables in the document can be changed
• .sdf files can be loaded into MS Word through the AP word add-in
• some of the text in an .sdf file can be modified, as long as it is text that is not tied to the logic
• .sdf files can be converted to .pdf (losing the ability to run logic)
• If the underlying platform / editor allows, contract logic embedded in .sdf files can be executed (through some API or UI part of the editor)
• .sdf document can be signed / encrypted to ensure their integrity
• .sdf documents can be sent to someone (and read/displayed etc) as any other document would

Possible content of an .sdf file:

./text/contract.md
./text/grammar.tem.md -- optional? could be through a reference to the template contract.md?
./logic/logic.wasm    -- probably safer than logic.js
./model/model.cto
./metadata.json

[jolanglinais]

This is super interesting, I like it! I'm a bit unclear about some of it though. Why wouldn't the .sdf have the template (.cta) within it? And would this mean that .cta is useful for creating a template, then once a user is happy with it they will finalize it into a .sdf?

[jeromesimeon]

This is super interesting, I like it! I'm a bit unclear about some of it though. Why wouldn't the .sdf have the template (.cta) within it? And would this mean that .cta is useful for creating a template, then once a user is happy with it they will finalize it into a .sdf?

really really good questions... my very well thought off answer to this is: I don't know.

To some extent, .sdf could be almost identical to our current .cta but there is a switch in perspective and some differences:

• don't think of a template sample sample.md but think of a real user document contract.md
• it's not an "archive" it's a "document"
• it's packaged for non-tempering of the logic (hence the wasm part -- and also it's compiled logic).
• unlike a template you cannot change the text that corresponds to the grammar
• it should also support free-text contract containing fixed-text clauses which we do not support in .cta right now.

There might be other differences that I am missing.

[jolanglinais]

Ahhh I think I'm getting it. So in .cta, the logic and text (sample.md) can be modified. But creating an instantiation of the .cta, which is a .sdf, compiles and locks the logic, and creates a (somewhat) locked version of the contract.md.

[jeromesimeon]

Ahhh I think I'm getting it. So in .cta, the logic and text (sample.md) can be modified. But creating an instantiation of the .cta, which is a .sdf, compiles and locks the logic, and creates a (somewhat) locked version of the contract.md.

yes exactly! (I think)

Also, there is a higher bar in portability and self-containedness that users expect with documents. The safety part is also really essential since it's really injecting code in lots of places. (ask security people about pdf...).

[pkel]

Cool stuff! I have two immediate thoughts on this.

(1) Taking the smart document thing to an extreme: why not embed all the "smart things" directly in a PDF? Smart documents could be named contract.smart.pdf for backwards compatibility with "non-smart" document viewers. Smart viewers could add smart features like simulation of cash flows, signing the contract, triggering clauses, payments, etc.

(2) After sending/receiving/viewing the contract, the next step is closing the contract. I think this still happens mostly via handwritten signatures on a printout? At least that's how it works here. A smart legal document should support a digital equivalent. I.e., appending signatures by multiple parties without breaking the previous signatures. We probably do not want to implement the necessary cryptography ourselves, though. Just keep this in mind when designing the format.

[jeromesimeon]

Cool stuff! I have two immediate thoughts on this.

(1) Taking the smart document thing to an extreme: why not embed all the "smart things" directly in a PDF? Smart documents could be named contract.smart.pdf for backwards compatibility with "non-smart" document viewers. Smart viewers could add smart features like simulation of cash flows, signing the contract, triggering clauses, payments, etc.

(2) After sending/receiving/viewing the contract, the next step is closing the contract. I think this still happens mostly via handwritten signatures on a printout? At least that's how it works here. A smart legal document should support a digital equivalent. I.e., appending signatures by multiple parties without breaking the previous signatures. We probably do not want to implement the necessary cryptography ourselves, though. Just keep this in mind when designing the format.

Interesting... Some lose thoughts on those:

(1) is pdf the right format? it's quite complicated. Some questions: how do you embed code in it? how do you get changes to the format adopted if you need to, how do you edit it, turn in into markdown, etc. It's an interesting thought, but feels very unrealistic based on what we have and ultimately hard to implement. (and possibly the wrong foundations if you want to embed e.g., wasm).

(2) very much agreeing with this. this should connect with the on-going discussion about legal signature / digital identity that we are having.

[martinhalford]

First... echoing @irmerk - super interesting!

My initial, thought bubble, is that this could be really useful. However, please can we **not call it a document?**

Therefore (sorry @jeromesimeon ), I'm not a fan of .SDF as the extension. My preference would be .SLC for smart legal contract - which is what it is.

I feel like we need to keep reinforcing the notion that these are not just documents.

I agree that we do need some sort of distinction between templates and instances, and being able to store metadata alongside the template data and logic would be awesome.

For example, this could be where we store digital signatures, certificates and hashes that are used by the contract when hosted on a Distributed Ledger or some such.

These signatures etc. could then be used to interact with Ergo logic and be used in (maybe) signing chain code deployed to DLT nodes (??). This could, also, tie into the Self-Sovereign Identity (SSI) stuff we have been discussing recently too.

I like to portability aspects of this idea too. In the future, .SLC contracts would be passed from system to system, and because they are signed etc., then .SLC contracts could be trusted like current, paper-based, notarised contracts are.

I'm sorry @pkel but I don't think PDF is the right format for this. There's too much baggage associated with the PDF format and, again, implies these are just documents.

...Martin

[dselman]

To clarify I suggest zooming out and describing what problems this is trying to solve, as a set of user stories.

My main worry is focus - I think we’ve got a couple of pressing issues to work on right now: pop-up editors and design mode, and supporting WASM and MS Word projects. Identity and signing is starting to get interest. Fabric integration as well... Then there’s high value additions to consider, such as table support.

[martinhalford]

Agree with zooming out and considering the bigger picture. This is probably a longer-term, strategic technical initiative.

Naively, I think, this might help with the identity and signing issues we have been discussing recently, and might even be of use with Fabric integration, maybe?

[martinhalford]

@jeromesimeon - another thought bubble.... Sometimes legal agreements reference other supporting documents/and or agreements.

For example, in Australia, a residential sale of land agreement includes such documents as land title details, building permits, any easements or caveats on the property, and the list goes on.... The actual contract incorporates all these documents.

Maybe certified/signed copies of such supporting documents could be stored within the contract instance too, maybe like this?

./text/contract.md
./text/grammar.tem.md -- optional? could be through a reference to the template contract.md?
./logic/logic.wasm    -- probably safer than logic.js
./model/model.cto
./metadata.json
./documents/
        land-title.pdf
        build-permit-no-1234.docx
        stamp-duty.txt
        ...etc...

Then, just to follow this rabbit hole deeper, sometimes legal agreements are dependent on preceding legal agreements.

For example, a power of attorney agreement empowers an individual to perform legal duties on behalf of another individual. In this case, a legal agreement (e.g. selling a property) signed by the person with power of attorney may need to reference the original power of attorney agreement.

Maybe we are entering a world where these agreements, when instantiated, can reference each other via some URI, and execute clauses accordingly. Hence, maybe, the contract instance could look like this?

./text/contract.md
./text/grammar.tem.md -- optional? could be through a reference to the template contract.md?
./logic/logic.wasm    -- probably safer than logic.js
./model/model.cto
./metadata.json
./documents/
        land-title.pdf
        build-permit-no-1234.docx
        stamp-duty.txt
        ...etc...
./includes.json -- stores URIs to externally referenced SLCs which, may or may not, have clauses executed as part of this SLC.

[tbrooke]

I like the SLC Extension and the references to external documents via URI -- II am not sure if this is the same or different from an SLC interacting, say, with a stream from an IOT device via Ergo.

Also I see the need for these to be signed with some sort of identity system since they are presumably interacting with either the external world or each other and you need to know which one (or ones) is authentic

[dselman]

Naming ideas:

1. Executable Document - edoc or exedoc or xdoc or xdc
2. Computable Document (or Cicero Document) - cdoc
3. Smart Document - sdoc
4. Smart Legal Contract - slc
5. CiceroMark Archive - cma

[peterhunn]

My $0.02 on naming. The .slc is well taken @martinhalford. I'm not so bearish on the reference to a document for at least two reasons:

1. A contract and a document are mutually exclusive. The contract is the agreement enforceable at law. What we actually have is a document that purports to record the agreement/contract.
2. That being said, I get the need to differentiate with a 'document' in the sense of say `.pdf'. Referencing a document does has baggage.
3. There is a divide in received terminology - many believe that 'smart legal contracts' can still be code that just exists on a blockchain or distributed ledger (despite the obvious problems with the 'smart contract' terminology).
4. Also, we have to be cognizant that this has to be exposed to the vagaries of any definition of a 'smart legal contract'. It has to be consistent.

I also have a preference to have 'cicero' as an implementation that is distinct from the format. There is an opportunity to develop a canonical format that helps move the industry forward.

(3) and (4) seem to be the most obvious to me, albeit not resolving the issue above.

.slc provides that canonical format for contract documents. .sdf doesn't have the baggage and creates room for an extension to other document types beyond contracts (even though that is the main focus today the community and others may wish to extend it).

[jeromesimeon]

Thanks @peterhunn for the thoughtful and very interesting feedback.

My $0.02 on naming. The .slc is well taken @martinhalford. I'm not so bearish on the reference to a document for at least two reasons:

(ouch, this double negation really hurt my brain).

1. A contract and a document are mutually exclusive. The contract is the agreement enforceable at law. What we actually have is a document that purports to record the agreement/contract.

Very interesting perspective.

2. That being said, I get the need to differentiate with a 'document' in the sense of say `.pdf'. Referencing a document does has baggage.

Agreeing.

3. There is a divide in received terminology - many believe that 'smart legal contracts' can still be code that just exists on a blockchain or distributed ledger (despite the obvious problems with the 'smart contract' terminology).

I've had that same experience, where the community I interact with think mostly "smart blockchain contract" first and the text is an afterthought. I would like to change that perspective.

4. Also, we have to be cognizant that this has to be exposed to the vagaries of any definition of a 'smart legal contract'. It has to be consistent.

I also have a preference to have 'cicero' as an implementation that is distinct from the format. There is an opportunity to develop a canonical format that helps move the industry forward.

Agreeing 100%. To me that is the central question in this issue.

(3) and (4) seem to be the most obvious to me, albeit not resolving the issue above.

.slc provides that canonical format for contract documents. .sdf doesn't have the baggage and creates room for an extension to other document types beyond contracts (even though that is the main focus today the community and others may wish to extend it).

I personally don't have a stake in .sdf I think the exact terminology and extension are subject to discussion and we want to make it: 1. clear and memorable 2. as clear to as many people as we can. 3. not already used somewhere else (you would be surprised at how many existing extensions there are!)

[peterhunn]

One other thing to bear in mind is existing usage e.g. Smart Documents and trademarks

[tbrooke]

I'm not sure we could come up with a new name and I think I like document. I think that smart contract has become a thing and all of the blockchains seem to have a variation of a smart contract in the solidity execute on the blockchain sense. I think it is too late and too confusing to keep having to explain the difference. Also since this is for an instansiated contract a document implies that it is finished and immutable. I can see for example a deal where you say we are negotiating a contract and then when you get it finished and signed you email it out and say here is your document. You could even keep them contract in the library and they don't become a document until they are executed.

The drawback, as Martin has indicated, is that a document implies a static thing but appending smart may make it less static.

[peterhunn]

.sld (Smart Legal Document) and .sla (Smart Legal Agreement) could be options too, but I don't think preferable over .slc or sdoc if they can work.

[martinhalford]

Hi All,

Sorry for the long post. I've tried to be as succinct as possible.

I think we are all broadly in agreement and I share many of the same conflicting thoughts.

@peterhunn wrote:

1. A contract and a document are mutually exclusive. The contract is the agreement enforceable at law. What we actually have is a document that purports to record the agreement/contract.

I agree with the distinction but, although what we currently have is a document, what we would like to have is a legally, enforceable agreement.

At the moment, there is no easy way to accomplish this - which is kinda the main aim of creating legal agreements.

Traditional paper (or PDF) agreements are printed and then signed. There is currently no equivalent in Accord.

The hypothesis is that end-users would benefit if there was some kind of portable, immutable, stand-alone, executable, digitally-signed "store" which would contain the entirety of the Cicero Template Archive, plus contain the specific contract data, digital signatures, metadata, attachments and any external references, that would encapsulate the entirety of the contract and allow it to be legally enforceable.

@peterhunn wrote:

2. That being said, I get the need to differentiate with a 'document' in the sense of say `.pdf'. Referencing a document does has baggage.
3. There is a divide in received terminology - many believe that 'smart legal contracts' can still be code that just exists on a blockchain or distributed ledger (despite the obvious problems with the 'smart contract' terminology).

All terminology comes with baggage. It will be an education process if we choose a new name and it will be an education process if we co-opt an existing name.

However, given the following is a possible format for the "store"....

./text/contract.md
./text/grammar.tem.md -- optional? could be through a reference to the template contract.md?
./logic/logic.wasm    -- probably safer than logic.js
./model/model.cto
./metadata.json
./documents/
        land-title.pdf
        build-permit-no-1234.docx
        stamp-duty.txt
        ...etc...
./includes.json -- URIs to other contract instances.

...I do not think we can call this a document - especially if it contains other documents or references to other contract instances comprising the legal agreement. At the very least, it is an archive instance.

Although there is some baggage associated with the name "Smart Legal Contract", as far as I am aware, this only really exists in the Crypto and Blockchain communities. Most consumers will be oblivious.

I like "Smart Legal Contract (.slc)" or "Smart Legal Agreement (.sla)" because it does what it says it does on the tin, and consumers will get the plain English meaning.

@peterhunn wrote:

I also have a preference to have 'cicero' as an implementation that is distinct from the format. There is an opportunity to develop a canonical format that helps move the industry forward.

I agree. Cicero can be the engine that generates the .CTA and instantiates the .SLC/.SLA but the format would be formally defined as a Standard (e.g. BSI [UK] or Standards Australia).

Some personal musings...

Although this would be a long-term, strategic undertaking, my personal belief is that, this would be a game-changer for the industry!

Using WASM for the executable, hashing and signing the archive store to make it tamper-proof and allowing it to be passed between parties like traditional paper contracts would be huge!

[dselman]

@martinhalford just an FYI that a docx file is a zip jam packed with xml (and other) files. Open Office XML; with docx extension to make it warm and fuzzy for end users!

[martinhalford]

@dselman wrote:

@martinhalford just an FYI that a docx file is a zip jam packed with xml (and other) files. Open Office XML; with docx extension to make it warm and fuzzy for end users!

Yep - agreed. I think this concept pushes the boundary of that distinction, and the aim of .DOCX is to print a document, so the DOCX name kinda makes sense in that context.

[tbrooke]

Just to add to the confusion I looked at Monax and they use the term "digital contracts".

[peterhunn]

I agree with the distinction but, although what we currently have is a document, what we would like to have is a legally, enforceable agreement.

Completely agree with the intention. The question of whether something is legally enforceable is usually (with some limited exceptions) not a matter of form. Just because something is packaged as a .slc etc does not render it a "smart legal contract". It just means it is in the form of a smart legal agreement. I think this is in contradistinction to a document as the document format itself defines validity. In other words, a .slc file may not be a contract at all (for a variety of reasons), but a .doc will be a document by definition. This is exacerbated when it becomes a multi-jurisdictional issue. It would be necessary to ensure the format follows standards guidance and also satisfies any future guidance as to form in statutes and regulations in order to be capable of appropriately operating as a smart legal contract.

This is all to say that I believe there is value in focus on the "format" (and presented as such) as much as I like the simplicity of .slc and equivalents. The SLC term is also gaining significant traction.

• Smart Contract Format .scf (quite like this)
• Smart Agreement Format .saf
• Executable Contract Format .ecf
• Smart Legal Contract Format .slcf

Just a thought....

[jeromesimeon]

Names are fun. I don't like "Smart Contract Format" because of "Smart Contract".

I do like:

• Smart Legal Contract Format (.slcf)
• Executable Document format (.xdoc, .xdf)

[martinhalford]

Names are fun but, at this point, given there's no obvious answer and given there are lots of ideas, maybe we leave the naming debate for the time being? :-)

Hopefully, as we evolve our understanding of what problem we are solving and how we are solving it, a self-evident name may emerge.

@peterhunn wrote:

The question of whether something is legally enforceable is usually (with some limited exceptions) not a matter of form. Just because something is packaged as a .slc etc does not render it a "smart legal contract". It just means it is in the form of a smart legal agreement.

This is, indeed, very true. In the same way, what makes a paper contract legally enforceable is not how it is written but how it is executed by the parties and the prevailing laws of the land.

The good news is that many jurisdictions are now accepting of digital sigs and, based on legal advice here in Australia, by extension, SLCs too.

It kind of makes sense that the next natural step would be to define a format and add functionality to, say, the Cicero libraries to allow end-users to generate these contracts as instances in that format.

The format will probably evolve as our understanding of the underlying legalities improves.

This is to be expected but could also mean that the Accord Project SLC format might become the default/defacto standard.

As an open-source project, an Accord format would be far more accepted by the industry than, say, a proprietary corporation's format.

[dselman]

xdf

I think this gets my vote of the proposals so far. "Executable Document Format" is nice and explicit, and as a three-letter-acronym it makes a nice reference to PDF. An alternative could be "Computable Document Format" (cdf).

[jeromesimeon]

xdf

I think this gets my vote of the proposals so far. "Executable Document Format" is nice and explicit, and as a three-letter-acronym it makes a nice reference to PDF. An alternative could be "Computable Document Format" (cdf).

I like the generality of both. Ultimately, the format could be used for all kinds of executable things, not only contractual.

NB: We will have more constraints than we think on extensions, so we definitely shouldn't get too excited about file extensions / names until we've researched that a bit more.

.xdf might be obscure enough that no one notices... https://fileinfo.com/extension/xdf

[frbrkoala]

The Structure of Contract Instance Archive

What contract instances should support:

• Export and import contract instances with it's history of executions between platforms (e.g. Clause.io <> BeNext)
• Run the logic and capture all outputs and states
• Support non-repudiation for all actions performed by contract parties (digital signatures)
• Encapsulate all the data (except the .cta files) into a PDF as invisible attachments without breaking the integrity

1. End-to-end contract lifecycle

1. Contract Instance is prepared by Party1 by combining Accord Project's contract templates with initialisation parameters and surrounding text and using Slate or Word editor
2. Contract legal prose is stored as CiceroMarkdown or PDF with metadata identifying sections of the agreement managed by Accord Project's contract templates with the reference to the SRC of a respective template together with it's hash (e.g. ap://latedeliverypenalty@0.14.0#HASHSTRING)
3. The Contract Instance's legal prose in .md or .pdf file is signed by Party1 and handed over to Party2 for co-signing
4. Party 2 examines the Contract Instance's legal prose in the .md or .pdf file and checks all the references to the Accord Project's contract templates to verify they can access those and that the hashes are correct. They can also examine and run unit tests to check the logic, embedded into the templates.
5. Party 2 signs the Contract Instance's legal prose that already contains references to the templates.
6. Party 2 shares the co-signed Contract Instance with Party1.
7. Party 1 or Party 2 runs the Init logic of all Accord Project's contract templates referenced in the Contract Instance's legal prose file. The output of the runs is added into a JSON file. The hash of the JSON file should be concatenated with the previous signature and the result string signed by the party who performed the run.
8. All subsequent runs of the logic within templates from the Contract Instance are added to it and signed in the same way.
9. The contract is closed when both parties co-sign the JSON file with the final state of the Contract Instance.

2. Performing contract amendments

1. Amendments can be done to the following portions of the legal prose:
   1. The text surrounding the templates
   2. Initialisation parameters of the existing templates
   3. Upgrade versions of the existing templates
   4. Adding new templates
2. Depending on the type of an amendment, it will require:
   1. If the change didn't involve the templates:
      1. Create the new version of the Contract Instance legal prose.
      2. Co-sign the legal prose
   2. If the change involved template's initialisation parameters:
      1. Create the new version of the Contract Instance legal prose
      2. Co-sign the legal prose
      3. One of the parties runs the "amend" logic of the template (templates have to provide the amending function)
   3. f the change was for the upgrade of the version of the template:
      1. Create the new version of the Contract Instance legal prose
      2. Co-sign the legal prose
      3. One of the parties runs the "upgrade" logic of the template (templates have to provide the upgrade function)

3. Contract Instance file structure

A .zip file, containing:

• package.json
  • name
  • displayName
  • description
  • accordproject
  • template: "contractinstance",
  • cicero: ,
  • runtime:
  • keywords: []
• prose/
  • <contract0.md | contract0.pdf>
  • ap://latedeliverypenalty@0.14.0#HASHSTRING
• identities/
  • cacerts/ [OPTIONAL for ECDSA only]
  • Party1CA.pem
  • Party2CA.pem
  • Party1.json
  • name: "Party1"
  • displayName [OPTIONAL]
  • description [OPTIONAL]
  • signatureType: <"SIMPLE"|"ECDSA_SHA_256"|"ECDSA_SHA_384"|"ECDSA_SHA_512" | "ECDSA_SECP256K1_KECCAK">
  • identityType: <"org.accordproject.party.Party" | "org.accordproject.organization.Organization">
  • cert: [OPTIONAL for ECDSA only]
  • Party2.json
  • name: "Party1"
  • displayName [OPTIONAL]
  • description [OPTIONAL]
  • signatureType: <"SIMPLE"|"ECDSA_SHA_256"|"ECDSA_SHA_384"|"ECDSA_SHA_512" | "ECDSA_SECP256K1_KECCAK">
  • identityType: <"org.accordproject.party.Party" | "org.accordproject.organization.Organization">
  • cert: [OPTIONAL for ECDSA only]
• templates/
  • latedeliverypenalty@0.14.0.cta
• state/
  • 0.json
  • 1.json
• runs/
  • 0.json
  • 1.json
• signatures.json
  • [
  • sign(Party1PK, hash(<contract0.md | contract0.pdf>)),
  • sign(Party2PK, sign(Party1PK, hash(<contract0.md | contract0.pdf>)))),
  • sign(Party1PK, concat(
    • sign(Party2PK, sign(Party1PK, hash(<contract0.md | contract0.pdf>)))),
    • hash(state/0.json),
    • hash(runs/0.json))
    • )
  • sign(Party2PK, concat(
    • sign(Party1PK, concat(
      • sign(Party2PK, sign(Party1PK, hash(<contract0.md | contract0.pdf>)))),
      • hash(state/0.json),
      • hash(runs/0.json))
        • ),
    • hash(state/1.json),
    • hash(runs/1.json))
    • )
  • ]

4. Contract ("happy") flows

Assembling the Contract Instance and prepare for run:

1. Extract metadata from package.json
2. Check Cicero version
3. Parse .md or .pdf to CiceroMark

Instantiating a new contract, first created and signed by Party1 and then co-signed by Party2:

1. Based on Contract templates and surrounding text in Slate format, generate CiceroMark
2. From CiceroMark generate MarkdownCicero or PDF with markings of beginning and end of each template's prose
3. Create Party1.json and, for ECDSA signature type, add Party1.pem and Party1CA.pem
4. Calculate the hash of <contract0.md | contract0.pdf>
5. Create the signature signatures.json [0] with Party1PK and the hash from 4.
6. Hand over the Contract Instance from Party1 to Party2.
7. Create Party2.jsonand, for ECDSA signature type, add Party2.pem and Party2CA.pem
8. Create the signature signatures.json [1] with Party2PK and the signature from 5.
9. Assemble contract instance (see "Assembling the Contract Instance and prepare for run")
10. For each template referenced in CiceroMark:
    1. Retrieve .cta file either locally from templates/ folder or from the catalog and convert to TemplateInstance
    2. Run init for write outputs to state/0.json and runs/0.json
11. [OPTIONALLY] put used templates .cta files into the templates/ directory
12. Create the signature signatures.json [2] with Party1PK, the signature from 7 and the hashes of state/0.json and runs/0.json

Run a clause from the contract instance:

1. Extract <contract0.md | contract0.pdf> and package.json
2. Assemble contract instance (see "Assembling the Contract Instance and prepare for run")
3. Based on the input, find a reference to a correct .cta file in CiceroMark
4. Retrieve .cta file either locally from templates/ folder or from the catalog and convert to TemplateInstance
5. Initialize Cicero with data from a respective node of CiceroMark
6. Get state/0.json, extract contract state
7. Run trigger the clause of TemplateInstance with contract state from 6 and write outputs to state/1.json and runs/1.json
8. Create the signature signatures.json [3] with Party2PK, the signature from signatures.json [2] and the hash of state/1.json and runs/1.json.

Verifying signatures:

1. Verify Party1.pem and Party2.pem with Party1CA.pem and Party2CA.pem
2. Calculate the hash of <contract0.md | contract0.pdf>
3. Verify the signature signatures.json [0] with Party1PK and the hash from 2.
4. Verify the signature signatures.json [1] with Party2PK and the signature from signatures.json [1].
5. Verify the signature signatures.json [2] with Party1PK, for concatenation of the signature signatures.json [1] and the hashes of state/0.json and runs/0.json
6. Verify the signature signatures.json [3] with Party2PK, for concatenation of the signature signatures.json [2] and the hashes of state/1.json and runs/1.json.

Close the contract instance:

1. Party1 verifies all signatures
2. Create the signature signatures.json [4] with Party1PK, the signature from signatures.json [3] and the hashes of state/1.json and runs/1.json.
3. Hand over the Contract Instance from Party1 to Party2.
4. Party2 verifies all signatures
5. Create the signature signatures.json [5] with Party2PK, the signature from signatures.json [4] and the hashes of state/1.json and runs/1.json.
6. Share the final version of the Contract Instance with Party1.

Sample signatures.json file:

[
    {
        "accordParty":"Party1",
        "signature":"BASE64",
        "prevSignature":null,
        "textId":0,
        "stateId":null,
        "runId":null
    },
    {
        "accordParty":"Party2",
        "signature":"BASE64",
        "prevSignature":0,
        "textId":0,
        "stateId":null,
        "runId":null
    },
    {
        "accordParty":"Party1",
        "signature":"BASE64",
        "prevSignature":1,
        "textId":0,
        "stateId":0,
        "runId":0
    },
    {
        "accordParty":"Party2",
        "signature":"BASE64",
        "prevSignature":2,
        "textId":0,
        "stateId":1,
        "runId":1
    },
    {
        "accordParty":"Party1",
        "signature":"BASE64",
        "prevSignature":3,
        "textId":0,
        "stateId":1,
        "runId":1
    },
    {
        "accordParty":"Party2",
        "signature":"BASE64",
        "prevSignature":4,
        "textId":0,
        "stateId":1,
        "runId":1
    }
]

5. Digital signatures

1. Two modes of operation:
   1. "SIMPLE" - no signature, only hashes. Used for testing, development and other special cases
   2. "ECDSA" - digital signatures with ECDSA_SHA_256 (key spec ECC_NIST_P256), ECDSA_SHA_384 (ECC_NIST_P384), or ECDSA_SHA_512 (ECC_NIST_P521).
2. Public keys for "ECDSA" are shared as PEM encoded X.509 certs within the <ACCORD_PARTY_NAME>.json files of the identities/ directory

6. Converting to and from PDF for sharing

1. The PDF is created from the latest version of the legal prose file
2. The whole .zip file is encoded as BASE64 and added at the end as attachment with an id like org.accordproject.slcf

[martinhalford]

Wow, Thanks @frbrkoala !! That's awesome work. Will revert shortly with comments. @tbrooke - Let's discuss this with Sanket for the Digitial Signing GSoC project.

[tbrooke]

Great effort @frbrkoala !! I really like the idea that a contract can be signed and that the state can be maintained as the contract executes with everything being maintained in a package so that the contract can run on any platform supporting Accord .

[frbrkoala]

Thanks @martinhalford and @tbrooke ! With such self-containing approach I am also aiming at using the dApp pattern from the blockchain world. That way all the parties need is the way to share the most recent version of the contract instance file (for example through Dropbox, box.com, etc.) and trigger web-form-driven clauses right in a browser with a wallet plugin. Digital signatures in this case can be done with a wallet like Metamask, for example, like this: https://github.com/MetaMask/eth-sig-util. I've added a new signature type "ECDSA_SECP256K1_KECCAK" to support that mode.

[martinhalford]

That's great @frbrkoala. I tend to agree that a fully self-contained approach would be ideal. However, we do need to accommodate old-school signing patterns for scenarios where users may not be able to use Metamask etc.

FYI... Not sure if you are aware but we have a Google Summer of Code project about to kick off with a student developer. It would be great if we could incorporate your thoughts and ongoing input into the project?

[frbrkoala]

Agreed, @martinhalford and that's where the "SIMPLE" should be handy. With that mode we just create hashes for data integrity verification and can be used in traditional signing.

Another reason what I think will make the dApps approach interesting is that it can bring some interest from the army of Ethereum developers as every contract essentially becomes a mini p2p blockchain network by itself.

And sure, will be happy to help with the project. Where can I find more info about it?

[tbrooke]

Sanket Shevakar at shevkar.sanket@gmail.com is the Google Summer of Code entrant. He is also on Slack and that may be the best place to reach him

@frbrkoala you have expressed and implemented what I have been thinking about for a while and if you can independently verify the state and content of a package on different platforms you can almost do away with the blockchain -- Blockchain has the public aspect but most contracts are between two parties or else a small group of parties -- As Martin says I like the Simple idea and I can sort of envision hooks that can be used by different signing methods - some sort of API

The interesting problem to me is - for example a note; the signing would be one thing and there are several ways to do that - but the payments would be automatically verified with a blockchain but without one it would require verification of all payments by each party and different versions of the contract would have to be kept in sync this would get difficult and maybe best left to the platform or blockchain

[frbrkoala]

@tbrooke @martinhalford , I've pinged Sanket, will share with him my thoughts, thank you!

And yes @tbrooke , I think I need to dive deeper into the ways contracts are digitally signed now in a more traditional scenarios. Is Docusign the type of service we are aiming at? If yes, then I believe "SIMPLE" approach will work.

As for the problem of agreeing on the shared state, I think it can be solved. Essentially what happens in systems like Hyperledger Fabric, is that the state of the peers is maintained through applying transactions, endorsed by different members of the network and sequenced in a correct order, deterministically for the whole network. Every peer validates transactions it receives and checks signatures and whether the suggested state change is correct, before deciding whether to accept it or not. It is handy when there are more than a couple of members and the transactions are coming at a fast pace. But with two parties, all we need to do is to allow two parties to validate the whole transaction history of the copy of the contract instance they have got. As long as they can keep their own copies of the previous version of the contract to verify the history has not been changed in the new version they received, it should be possible for them to verify the latest recorded contract runs by re-running them with the same inputs and making sure they produce the same outputs (that's what the peers are doing to "endorse" transactions in Hyperledger Fabric).

That means that, for example, when Party1 executes a clause, which issues a payment obligation to be fulfilled by Party2, the Party2, once it receives the new copy of the contract instance, can validate it, re-run the logic of the same clause and make a decision based on the output they see, including all the calculations for their payment obligation.

Where blockchain (or a centralised system) will be handy is in enforcing the payment itself (or transferring the ownership rights on some asset). If the blockchain system has an embedded currency and a way to perform a transfer of funds automatically, the funds for fulfilling the payment obligation can be locked or even performed from an "escrow" account, controlled by the contract. It can also be done post factum, when the contract is closed and co-signed by both parties.

[jeromesimeon]

@frbrkoala @martinhalford @tbrooke This is fantastic. Also a lot to absorb. I'm wondering if there is a way for me to catch up/get involved in the design and discussion around this?

[martinhalford]

@jeromesimeon - The more the merrier! I'm thinking to create a Google Doc to capture all of the above in a single place, so we can edit/comment accordingly. That might be easier than trawling the trail of comments. What is your preference?

We're also, probably, going to need a Github Project. I'm conscious that Sanket will be working on some of the above for the GSoC project and it would be good to demarcate that work.

[sanketshevkar]

@frbrkoala @tbrooke @martinhalford this looks amazing. I think the approach I described in my gsoc proposal can easily be integrated with the approach proposed by @frbrkoala above.

[dselman]

Nice work @frbrkoala - this makes sense to me. Essentially this pushes the "ledger" into the zip and we provide the code to process transactions and to verify the transaction history. It's not a million miles away from how the AP Fabric chain code operates. As an aside, we still need to solve for the problem that "only party A can process transaction X" via Ergo enforce expressions over the identity of the party submitting a transaction.

[pkel]

Great proposal @frbrkoala!

As for the problem of agreeing on the shared state, I think it can be solved. Essentially what happens in systems like Hyperledger Fabric, is that the state of the peers is maintained through applying transactions, endorsed by different members of the network and sequenced in a correct order, deterministically for the whole network. Every peer validates transactions it receives and checks signatures and whether the suggested state change is correct, before deciding whether to accept it or not. It is handy when there are more than a couple of members and the transactions are coming at a fast pace. But with two parties, all we need to do is to allow two parties to validate the whole transaction history of the copy of the contract instance they have got. As long as they can keep their own copies of the previous version of the contract to verify the history has not been changed in the new version they received, it should be possible for them to verify the latest recorded contract runs by re-running them with the same inputs and making sure they produce the same outputs (that's what the peers are doing to "endorse" transactions in Hyperledger Fabric).

That means that, for example, when Party1 executes a clause, which issues a payment obligation to be fulfilled by Party2, the Party2, once it receives the new copy of the contract instance, can validate it, re-run the logic of the same clause and make a decision based on the output they see, including all the calculations for their payment obligation.

Where blockchain (or a centralised system) will be handy is in enforcing the payment itself (or transferring the ownership rights on some asset). If the blockchain system has an embedded currency and a way to perform a transfer of funds automatically, the funds for fulfilling the payment obligation can be locked or even performed from an "escrow" account, controlled by the contract. It can also be done post factum, when the contract is closed and co-signed by both parties.

This observation is important. Legal contracts usually involve a small number of identified parties. In these cases, agreeing on a common state is relatively straightforward. Like @frbrkoala says, one potential solution is that all involved parties sign the latest state. If a party refuses to sign and thereby blocks progress, you can rely on legal recourse to resolve the issue.

Blockchain tech enables agreement between a huge number of (legally) unidentified parties. It might be useful for social contracts like money where generally nobody trusts anybody. IMO it is overkill for business relationships where trust is fundamental anyway.

Whether blockchain or not, it is crucial to establish a unique order of the state updates (transactions). State updates must be authorized/signed against a distinct preceding state. That's the chaining aspect in blockchains. For off-chain applications it might be more practical to enumerate the transactions (per contract instance) and check that every index is used exactly once.

[pkel]

Have you thought about encoding the signatures as special kind of transactions? E.g. a series of transactions for a contract lifecycle could look like this.

1. init. Party A initializes the instance.
2. fund 100. A deposits 100 units.
3. sign. A signs all transactions up to 2. Thereby, A certifies that it is willing to enter a contract with B funded with 100 units.

Party A sends the contract instance to party B. B checks that 1 to 3 are valid.

4. fund 100. B deposits 100 units.
5. sign. B signs all transactions up to 4. Thereby, B certifies that it enters the contract with A. It also certifies that it deposited another 100 units.

Party B sends the contract to party A. A checks that 1 to 3 are unchanged and that 4 to 5 are valid.

6. sign. A signs all transactions up to 5. Thereby, A certifies that it is aware of B entering the contract and depositing another 100 units.

Party A sends the contract to party B. B checks that 1 to 5 are unchanged and that 6 is valid.

Now, all parties are aware of the latest state. They also know the number of the last transaction 6. Any party could continue the lifecycle by adding a transactions starting from index 7.

Maybe such an encoding can make the system more modular. Updating and signing could happen at separate departments of a corporation. Advanced signature schemes (e.g., CA based) could be added as separate transaction types.

[pkel]

Do you plan to make the last signed state available to the contract logic? Then, the logic could specify signature requirements (e.g., close clause expects signatures on the last state by all parties)

[martinhalford]

Hi @pkel @frbrkoala @sanketshevkar @tbrooke etc... This is all really great thinking and I'd love to see some of these ideas implemented.

However, my initial reaction is that we need to keep things relatively simple to start with and resemble real-world usage as much as possible.

The typical user journey for a legal contract (as opposed to a blockchain contract) is:

1. Draft (Template) mode: Parties negotiate the terms of the agreement and populate the contract template with data.

2. Signing-in-progress (Instantiate) mode: At least one party signs the agreement which, effectively, instantiates an instance of the contract with the data provided. At this point, the contract is now immutable and other parties can choose to sign or not sign the instantiated contract.

3. Signed (Execution) mode: All parties have signed the contract and so now - and only now - is the contract legally enforceable. This is the mode whereby users can now Trigger clauses, emit Obligations and the Contract State becomes a thing.

The above is the user journey we are using for the real estate industry here in AU. The only difference is we have also added:

4. Superseded mode: This can be triggered during "Signing-in-progress" mode when one of the parties decides that they are unwilling to sign the contract and want to make amendments. This creates a new version (e.g. v2.0) of the contract in "Draft (Template) mode" and marks the instantiated contract (e.g. v1.0) as superseded - and the whole process starts again.

[martinhalford]

@tbrooke @jeromesimeon @dselman @pkel

FYI... Today, @frbrkoala, @sanketshevkar and I had a brainstorming session around contract instances and signing.

The attached diagram is a further refinement on the above but still very much a work-in-progress.

The focus is simplicity, minimising complexity and trying to make sure the user journey fits real-world scenarios.

https://docs.google.com/drawings/d/1idtGSdXpCgjQM8-wG4wUC5oKp7SeHEtcL2MzRMTK5lg/edit?usp=sharing

OBJECTIVE The main aim, as we see it, is to enable parties to legally sign an instance of an Accord Project contract. This is distinct from a template developer signing a contract template.

ASSUMPTIONS

• Only Contract Instances are signed. There is no provision to sign a Clause Instance
• There is a one-to-many relationship between a Contract Template (.cta) and a Contract Instance (.cia)
• That is, a Contract Instance (.cia) is instantiated from a single Contract Template (.cta) only, but a Contract Template can instantiate many Contract Instances.
• A Contract Instance (.cia) contains a complete copy of the Contract Template (.cta) that created it but the Contract Instance completely severs any references to dependencies. That is, the Contract Instances are immutable.

NEW COMMANDS

• instantiate

  • “instantiate” command creates contract instance (.cia) by copying .cta file, taking in data.json or data.md as parameter, and creating a new “instance archive” (.cia).
  • “instantiate” command throws an exception if data.json or data.md exists, as assumes template already instantiated.
  • Use “--supersede” flag to override, accept a new data.json/data.md file and create a new CIA instance with Version Number in Package.json incremented.

• sign

  • “sign” command only available for contract instances, not templates.
  • "sign" command takes "party.json" file and invokes signing process (This will need to be fleshed out further).
  • "party.json" should match parties defined in /model/model.cto and /data/data.json

• parties

  • List of all parties - as defined in data.json (or data.md) and display which parties have signed - as defined by party1..partyN json files.
  • Once all parties signed the contract becomes fully “executed”. Meaning that the contract is now legally binding, as all parties have lawfully signed contract.
  • “sign” command will throw an exception as all parties have signed.

[mttrbrts]

I like it! The graphic is very helpful. A few thoughts ...

Only Contract Instances are signed. There is no provision to sign a Clause Instance

Should this read "Only Cicero Instances are signed. There is no provision to sign a Cicero Template"?

However, I see value in being able to verify the author of a template (which could be achieved through a Digital Signature). This is a different use of "signing".

Question: What is the scope of @sanketshevkar's project? Is it verifying the originator for templates, or the identity of parties to an instance?

The former is more immediately addressable and doesn't depend on completing this instance design work, however, arguable the latter is more valuable.

A Contract Instance (.cia) contains a complete copy of the Contract Template (.cta) that created it but the Contract Instance completely severs any references to dependencies. That is, the Contract Instances are immutable.

I appreciate the benefits of static bundling for the instance, however removing the reference to the source dependencies in the template means that you are not able to trace the lineage of the instance. For example, it's reasonable to ask, "which templates were used to create this instance?". I would advocate for retaining the dependencies as metadata.

DRAFT --> UNSIGNED --> SIGNING IN PROGRESS --> EXECUTED

Are UNSIGNED and SIGNING IN PROGRESS both the same step, but with different number of signatures received? I believe the same operations would apply in both cases. For example cicero parties would return an empty list in the UNSIGNED stage.

Also, when discussing this, I typically refer to EXECUTED as RUNNING to indicate the liveness aspect and to avoid the legal overloading of "execute".

[frbrkoala]

Hi @pkel ! Yes, the idea is to keep track of all signatures in a dedicated file (s) that looks as a transactions log, but essentially it contain the information about who performed an operation, their signature and references to the artefacts involved (the version of prose, state or run results). The only requirement is for the signatures to be added sequentially, so that it will be clear that subsequent signer was aware of the latest state of the contract instance. And yes, the whole "closing" process is to make sure the final state is clear and all agree to it.