# Decombine Smart Legal Contract Specification (DRAFT) **Version**: 0.1.0 **Date**: February 11, 2025 **Authors**: - Timothy Tavarez <[email protected]> | Founder, CEO - Decombine ## Introduction --- The Decombine Smart Legal Contract (SLC) is specification and SDK to perform programmatic contractual execution in a standardized, templated, and declarative way. Decombine SLC are not a replacement for natural language contracts, but instead, a means to augment conventional contracts. A conventional contract may dictate thousands of varying requirements, conditions, and actions. A Decombine SLC can be used to translate these into a software package that supports mathematical verification, flexible deployment strategies, and infinitely customizable scenarios. The Decombine SLC was invented to offer an accessible, transparent, and cloud-native way for parties to form an agreement. A SLC ensures transparency about *what* will happen and *when*. In contrast to conventional agreements where a digitized contract may be created and then all other processes are separate, an SLC instead integrates contract-related processes into an end-to-end workflow. SLC can include natural language-based contractual language or be purely automated business logic. A mixture of these is generally expected to cover most use cases. SLC are designed to augment conventional document-based agreements that may or may not be associated with automated business processes. SLC are distinct from blockchain-based smart contracts. SLC use conventional APIs, a simple Finite State Machine implementation, and are operated on traditional compute such as Kubernetes, as opposed to ledgers and state virtual machines favored by most blockchain implementations. SLC can be connected to an Agreement Network that enables identity federation, complex policies, brokerage, and additional functionalities. SLC may be self-hosted or use remote orchestration services. ### Why Decombine Smart Legal Contracts? **Transparency** The lack of insight into *what* happens *when* we form agreements mandates a reliance on good faith and an implicit trust. Smart Legal Contracts offer an alternative where the lifecycle of an agreement is dictated by auditable, traceable, and clear templates. **Consistency** Templates are portable, idempotent, and predictable. They ensure once written and employed, there will be little guesswork involved. **Accessibility** Smart Legal Contracts can be used to build anything from simple, quickly completed workflows to more complex systems providing long-running and repeatable functionality, such as an entirely declarative e-commerce business. Smart Legal Contracts can democratize access to complicated and expensive services by standardizing them. ### Design Influences 1. Prefer cloud-native tools 2. Plan for GitOps as standard practice 3. Favor simplicity and explicitness over abstractions ## Smart Legal Contract Structure --- ```mermaid --- title: SLC Structure --- mindmap root((SLC)) Sources Policies Actions Texts State %%{ init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#BB2528', 'primaryTextColor': '#fff', 'primaryBorderColor': '#7C0000', 'lineColor': '#F8B229', 'secondaryColor': '#006100', 'tertiaryColor': '#fff' } } }%% ``` Smart Legal Contracts are defined in a standardized schema that can be implemented in JSON, YAML, or TOML formats. The SLC format contains references to the components that make up the functionality. SLC contain the following major components: 4. **Sources**: The origin of the content. 5. **State**: The composition of the State Configuration dictating the SLC lifecycle. 6. **Policies**: Rules that can be applied to the SLC and its execution environment. 7. **Texts**: Text templates for natural language contract records or references. 8. **Actions**: Software payloads executed in different states. The major components are domain-oriented, and will implement new or different capabilities over time. It is expected that while the overall structure may be relatively consistent, individual components will evolve to support new use cases/capabilities. ### SLC Definition Schema The SLC schema can be implemented in JSON, YAML, or TOML. - YAML 1.2 (Revision 1.2.2)[^1] is the minimum release specification for YAML. - JSON Schema 2020-12[^2] is the minimum release specification for JSON. - TOML v1.0.0[^3] is the minimum release specification for TOML. ```json name: "The Fellowship Non-Disclosure Agreement" version: "0.1.0" text: url: "https://github.com/thefellowship/nda/texts/index.html" source: url: "https://github.com/thefellowship/nda" branch: "main" path: "contract.json" policy: branch: "main" directory: "/policies" url: "https://github.com/thefellowship/nda" state: initial: "Keep it secret, keep it safe" url: "https://github.com/thefellowship/nda" states: - name: "Draft" ... ``` ### Sources Sources provide the content the SLC is composed from. Multiple sources may be used for different components to enable complex composition scenarios or a single source can be used. - Sources must be network-accessible endpoints. - Sources must be provided for all components in `text`, `source`, `policy`, and `state`. - Sources support Git repositories over HTTP(S) and SSH. Sources can be used to provide a continuous deployment source that is synchronized by an SLC runtime to perform reconciliation, drift detection, and pruning. ### State State communicates the lifecycle of the SLC. SLC can only ever be in one state at any one time. States may be associated with declaratively defined software payloads that are triggered by transitions between states. Transitions are in turn triggered by specific events and conditions. - State is implemented as a Finite-state machine[^4] based on the theory of Unified Modeling Language (UML) state machine[^5]. State is referred to as the State, State Configuration, or Tree. - State must be provided for SLC. A valid SLC must contain one or more states in the `state`. - State always begins in the `initial` state identified in `state`. ```mermaid stateDiagram-v2 state Unsigned state Incomplete state Signed state Expired [*] --> Unsigned Unsigned --> Incomplete: First signature Incomplete --> Signed: All signatures complete Incomplete --> Expired: Expiration date reached Signed --> Expired: Expiration date reached Expired --> [*] ``` #### Transitions - Transitions must be triggered by events. - Transition can occur between any two states (the *main source* and *main target*). - Transition involves exiting all nested states from the current active state up to, but not including, the *least common ancestor (LCA)* of the *main source* and *main target* states. #### Events Events are structured payloads that may be published or subscribed to. Events for SLC use the [CloudEvents](https://cloudevents.io) schema. - Events are described using CloudEvents[^6]. - Event refers to the type of occurrence rather than to any concrete instance of that occurrence. - Events may have associated *parameters*. - Event lifecycle is *received*, *dispatched*, and *consumed*. - Received when an event instance is accepted and waiting for processing. (E.g., added to queue) - Dispatched when an event instance becomes the current event (E.g., beginning processing) - Consumed when an event instance is finished being processed by the state machine (E.g., removed from queue) **Events deferral** - Events may deferred within specific states by declaring it in a deferral list. Upon transition to a state that does not contain the deferral in its list, the event may be processed/discarded. - It is possible for a superstate to have a transition defined on an event that is deferred by a substate. #### Guard Conditions State transitions may be associated with conditions, known as guard conditions. - Guard conditions are evaluated dynamically based on the value of *extended state variables* and *event parameters*. E.g., `[signature_count == 0]` - Guard conditions should enable actions or transitions only when they evaluate to `true`. - Guard conditions should be side-affect free. ### Actions Actions are the software payloads executed in different states. Actions are defined under the State Configuration, but are their own component with separate versioning and development. Actions may be any arbitrary code, but are currently executed natively within the Kubernetes runtime as extended API resources. - Actions (both entry and exit actions) are associated with states, not transitions. - Actions are akin to guaranteed initialization and cleanup such as class constructors and destructors. - Action parameter values associated with the current event are available to all actions directly caused by that event. - Action order of execution of entry actions must always proceed from the outermost state to the innermost state (top-down). ```yaml ... states: - name: "Draft" transitions: - name: "Complete" to: "Complete" from: "Draft" entry: actionType: "kubernetesAction" kubernetesAction: - name: "start-nda-workflow" namespace: "default" kustomizationSpec: path: "actions/draft" targetNamespace: "default" interval: "10m" prune: true sourceRef: kind: "GitRepository" name: "nda" ... ``` #### Kubernetes Actions Kubernetes Actions provide support for scheduling Actions defined as using Kustomization API[^8] provided by [Flux](https://fluxcd.io/). Kustomization-based Kubernetes Actions enable workloads of arbitrary complexity to be run in the scope of an Action, supporting reconciliation and pruning. ### Policies Policies are controls (rules) applied to the SLC and runtime through declarative templates. Policies are loaded alongside any SLC runtime such as Kubernetes using standardized formats. Policies are implemented using Open Policy Agent (OPA) and/or Kyverno. - Policies are stored in version-controlled repositories. - Policies can be templated files or packaged using a OCI-compatible format. ### Texts Texts provide references for natural language contracts or records. Conventional digitized contracts typically have Microsoft Word, PDF, or other types of records that provide historical reference and shared context. SLC are not prescriptive about the usage of texts. Users should use the text or record formats that best suit their needs. Texts are not legal advice or a replacement for professional legal services. - Texts may be provided as any arbitrary document (Word, PDF, HTML, Markdown, etc.). - Texts may implement different capabilities depending on their format. - Texts may be referenced by States. - Text of some kind must be provided in `text` to form a valid SLC. #### Templates Text templates are provided as a specification to set a baseline capability that may be optionally implemented. Text templates are source controlled and pulled from networked (Internet, private network, etc.) repositories. Each template is associated to specific ISO 639 language[^7], version, and digital signature. Templates may be cryptographically hashed prior to parameter interpolation. The signature string is stored within the metadata. Prior to templates being compiled into a document, the templates are verified to match their signatures. - Templates are stored in version-controlled repositories. - Templates are files on disk with the `.md` file extension. - Templates may use in-file frontmatter to provide metadata. - Templates may also use a dedicated `.yaml` manifest to provide metadata. - Templates are addressed using `<author>/<content-name>` similar to OCI standard. - Templates may optionally include data models. If there are any parameters included in the template, data models must be included. ```yaml --- name: 'public-nda' version: '4.5' author: 'decombine' models: - name: '[email protected]' classes: - Options signature: value: 62FCBBFC7C26840AD03DF1DE64596C14E62F5C9DCC23AFBFD27B9A52339C773E algo: SHA256 --- ``` ##### Parameterized Texts Texts can be parameterized to customize the generated agreements. Parameters are associated to values in [[#Data models]] and inserted into generated outputs such as Markdown, HTML, and PDF. ## References [^1]: [YAML Ain’t Markup Language (YAML™) revision 1.2.2](https://yaml.org/spec/1.2.2/) [^2]: [JSON Schema 2020-12](https://json-schema.org/draft/2020-12/json-schema-core) [^3]: [TOML: English v1.0.0](https://toml.io/en/v1.0.0) [^4]: [Finite-state machine - Wikipedia](https://en.wikipedia.org/wiki/Finite-state_machine) [^5]: [UML state machine - Wikipedia](https://en.wikipedia.org/wiki/UML_state_machine) [^6]: [CloudEvents |](https://cloudevents.io/) [^7]: [ISO 639 - Wikipedia](https://en.wikipedia.org/wiki/ISO_639) [^8]: [Kustomization | Flux](https://fluxcd.io/flux/components/kustomize/kustomizations/)