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://[email protected]#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: <ciceroVersion>,
    • runtime:
  • keywords: [<Array_of_Key_Words>]
• prose/
  • <contract0.md | contract0.pdf>
    • ap://[email protected]#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: <Party1.pem> [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: <Party2.pem> [OPTIONAL for ECDSA only]
• templates/
  • [email protected]
• 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 <contract0.md> or PDF with markings of beginning and end of each template's prose <contract0.pdf>
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:
11. Retrieve .cta file either locally from templates/ folder or from the catalog and convert to TemplateInstance
12. Run init for write outputs to state/0.json and runs/0.json
13. [OPTIONALLY] put used templates .cta files into the templates/ directory
14. 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.