From 814d9ae42eabaeb427ed9455420f70899b16d4a8 Mon Sep 17 00:00:00 2001 From: Felix Hoops <9974641+jfelixh@users.noreply.github.com> Date: Mon, 2 Dec 2024 17:43:56 +0100 Subject: [PATCH 1/2] Propose EVES-005 Signed-off-by: Felix Hoops <9974641+jfelixh@users.noreply.github.com> --- EVES/drafts/EVES-005/eves-005.md | 94 ++++++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 EVES/drafts/EVES-005/eves-005.md diff --git a/EVES/drafts/EVES-005/eves-005.md b/EVES/drafts/EVES-005/eves-005.md new file mode 100644 index 0000000..d0c6052 --- /dev/null +++ b/EVES/drafts/EVES-005/eves-005.md @@ -0,0 +1,94 @@ +--- +eves-identifier: 005 +title: Contract Negotiation Process +author: Felix Hoops (@jfelixh) +discussions-to: https://github.com/ASCS-eV/EVES/issues/ +status: Draft +type: Process +created: 2024-12-02 +requires: ["EVES-001"] +replaces: None +--- + +## Abstract + +A market place requires processes for publishing assets, negotiating contracts, and settling these contracts as a basis for services and billing. We focus on the negotiation process, since it influences all of the other mentioned steps. This document is not a technical specification, but rather a high-level process description. Data standards and specific technology choices must be settled separately. + +## Motivation + +Gaia-X specifications on the topic are high-level (refer to [this](https://docs.gaia-x.eu/technical-committee/architecture-document/24.04/other_concepts/#computational-contracts)) and existing implementations like the Eclipse Dataspace Connector's [negotiation](https://github.com/eclipse-dataspace-protocol-base/DataspaceProtocol/blob/main/negotiation/contract.negotiation.protocol.md) are complex. Beyond that, we have specific goals that are not fulfilled by any specification we are aware of at the time of writing: + +1. Ensure that the market place can mandate the use of pre-approved contract templates to ensure fairness and collect proportional fees. +2. Finalize contracts in a way that makes them fully provable to third parties, including timestamp, to give legal security to participants. +3. Limit the information that external parties or the market place operator have access to to a minimum required for safe operation. +4. Allow providers to make individual contracts per consumer if desired. +5. Represent the contracts as W3C Verifiable Credentials to leverage synergies with existing components in the decentralized ecosystem, specifically to easily make them usable for access control. + +## Specification + +### 1. Stakeholders + +The ENVITED-X market place _operator_ provides and maintains the market place infrastructure. The operator also acts as a trust anchor giving access and verifiable identities to participants. For these services, the operator collects fees from providers based on sales volume. + +The _provider_ is interested in selling an asset. + +The _consumer_ is interesting in buying an asset. + +### 2. Initial Setup + +The operator must set up a smart contract that allows anyone to retrieve a set of acceptable contract templates, which should have the form of ODRL policies. + +The operator must run a _settlement service_ that can be used to settle contracts. Contract credentials are only considered valid once their hash has been submitted to this service, which publishes the hash (directly or indirectly) on a blockchain. + +We assume that the provider and consumer run a _negotiation service_ that consists of frontend and backend. It could be a part of other infrastructure, such as the dataspace connector. This services takes over communication between provider and consumer. + +### 3. Asset Setup + +The provider must register an asset as described in EVES-003. + +### 4. Negotiation Process + +The consumer uses metadata search or similar services to identify an asset of interest, before he contacts the provider to negotiate a contract. + +1. The consumer asks the provider for a contract offer (i.e., quote) for the asset. +2. The provider creates a contract offer referencing a contract template. This offer contains specific data, such as pricing and usage requirements. +3. The provider sends the contract offer to the consumer in the form of a Verifiable Credential. +4. The consumer checks that the offer is correctly signed and that it references a valid contract template. The offer may not conflict with the template. +5. If the consumer accepts, he constructs a contract credential, which wraps the contract offer. +6. The consumer sends this contract credential back to the provider, to ensure that both parties have the full contract without involving a third party. +7. The provider validates the contract credential. In this step, the provider could also choose to ignore the contract. For example, if the offer has expired. +8. The provider sends the hash of the contract credential to the operator's settlement service. +9. The settlement service locally saves the hash and which provider sent it. Then, the service commits just the hash to the public blockchain. +10. The consumer and provider monitor the blockchain to see if the contract has been settled. + +At this point, the contract is fully settled and the consumer can use the asset. + +### 5. Fee Payment + +On a regular basis, the providers send the accumulated fees to the operator. To ensure the fees are correctly calculated without publishing business statistics, a provider should construct a zero knowledge proof for the accumulated amount being correct based on the submitted hashes. + +### 6. Limitations and Discussion + +We assume that the provider and consumer have an interest in properly time-stamping their contract agreement. This interest ensures that the operator is aware of any transaction that may generate fees. + +Provider and consumer may add a status entry to their Verifiable Credentials to mark the contract or the offer in some way. This could be useful in the case of a legal dispute to give a contract a disputed status or even entirely revoke it. + +This negotiation process heavily limits data exposure, but some information beyond what what is exposed by necessity and design can still be learned: + +1. Third Party + + - Can read number of contract agreements happening on the entire market place in a given time period. + +2. Operator + + - Knows the number of contract agreements happening in a given time period for a given provider. + +## Backwards Compatibility + +This process does not conflict with prior EVES. + +## References + +## Implementation + +This process is not yet implemented. From cf5fea86654a5baa2c2a88badb847eca6002e0b1 Mon Sep 17 00:00:00 2001 From: jdsika Date: Wed, 4 Dec 2024 17:01:02 +0100 Subject: [PATCH 2/2] EVES-005 minor editorial changes. Ensured 1 line per sentence across EVES. Add feedback to EVES-004 Signed-off-by: jdsika --- EVES/SUMMARY.md | 7 +++-- EVES/drafts/EVES-001/eves-001.md | 8 +++-- EVES/drafts/EVES-003/eves-003.md | 8 +++-- EVES/drafts/EVES-004/eves-004.md | 8 +++-- EVES/drafts/EVES-005/eves-005.md | 53 ++++++++++++++++++++------------ EVES/resources/eves-template.md | 2 +- README.md | 7 +++-- 7 files changed, 58 insertions(+), 35 deletions(-) diff --git a/EVES/SUMMARY.md b/EVES/SUMMARY.md index 42ef16c..81ad017 100644 --- a/EVES/SUMMARY.md +++ b/EVES/SUMMARY.md @@ -6,7 +6,8 @@ ## EVES -* [EVES-001: ENVITED Ecosystem Specification Process](drafts/EVES-001/eves-001.md) +* [EVES-001: ENVITED-X Ecosystem Specification Process](drafts/EVES-001/eves-001.md) * [EVES-002: ENVITED-X Data Space Architecture Overview](drafts/EVES-002/eves-002.md) -* [EVES-003: ENVITED Asset Definition and Upload Process](drafts/EVES-003/eves-003.md) -* [EVES-004: Roles and Responsibilities of EVES Editors](drafts/EVES-004/eves-004.md) +* [EVES-003: ENVITED-X Asset Definition and Upload Process](drafts/EVES-003/eves-003.md) +* [EVES-004: ENVITED-X Roles and Responsibilities of EVES Editors](drafts/EVES-004/eves-004.md) +* [EVES-005: ENVITED-X Contract Negotiation Process](drafts/EVES-005/eves-005.md) diff --git a/EVES/drafts/EVES-001/eves-001.md b/EVES/drafts/EVES-001/eves-001.md index 807d0de..2eaa802 100644 --- a/EVES/drafts/EVES-001/eves-001.md +++ b/EVES/drafts/EVES-001/eves-001.md @@ -1,6 +1,6 @@ --- eves-identifier: 001 -title: ENVITED Ecosystem Specification Process +title: ENVITED-X Ecosystem Specification Process author: Carlo van Driesten (@jdsika) discussions-to: https://github.com/ASCS-eV/EVES/issues/9 status: Draft @@ -17,7 +17,8 @@ These specifications standardize and document implementation decisions for the E ## Motivation -A standardized process for EVES ensures clarity, inclusivity, and accountability in the evolution of the ENVITED ecosystem. By defining roles, responsibilities, and lifecycle stages, this process aligns with best practices from similar initiatives, such as Chain Agnostic Improvement Proposals (CAIPs). +A standardized process for EVES ensures clarity, inclusivity, and accountability in the evolution of the ENVITED ecosystem. +By defining roles, responsibilities, and lifecycle stages, this process aligns with best practices from similar initiatives, such as Chain Agnostic Improvement Proposals (CAIPs). ## Specification @@ -129,7 +130,8 @@ All EVES documents must adhere to the following structure: ### 8. Governance -The process emphasizes openness, inclusivity, and accountability. Discussions, decisions, and documentation are publicly accessible on the EVES GitHub repository. Governance rules for EVES Editors are defined [here](https://openmsl.github.io/doc/OpenMSL/organization/governance_rules.html). +The process emphasizes openness, inclusivity, and accountability. Discussions, decisions, and documentation are publicly accessible on the EVES GitHub repository. +Governance rules for EVES Editors are defined [here](https://openmsl.github.io/doc/OpenMSL/organization/governance_rules.html). ## Backwards Compatibility diff --git a/EVES/drafts/EVES-003/eves-003.md b/EVES/drafts/EVES-003/eves-003.md index 9f15e44..a516072 100644 --- a/EVES/drafts/EVES-003/eves-003.md +++ b/EVES/drafts/EVES-003/eves-003.md @@ -1,6 +1,6 @@ --- eves-identifier: 003 -title: ENVITED Asset Definition and Upload Process +title: ENVITED-X Asset Definition and Upload Process author: Carlo van Driesten (@jdsika) discussions-to: https://github.com/ASCS-eV/EVES/issues/4 status: Draft @@ -127,7 +127,8 @@ The synchronization between the smart contract and the ENVITED-X database relies #### TZIP-21 rich metadata mapping -Attributes not in the table are static and the same for every mint. Examples are the first five tags or "publishers", which is always ENVITED-X and the ASCS as the mint is conducted through the website. +Attributes not in the table are static and the same for every mint. +Examples are the first five tags or "publishers", which is always ENVITED-X and the ASCS as the mint is conducted through the website. | TZIP-21 | EVES-003 | Comment | | -------------------| ---------------------------------------------------- | ------------------------------------------------------------ | @@ -156,7 +157,8 @@ Attributes not in the table are static and the same for every mint. Examples are ## Backwards Compatibility -This specification introduces new processes for asset uploads and is fully compatible with existing ENVITED-X systems. No retroactive changes to previous assets are required. +This specification introduces new processes for asset uploads and is fully compatible with existing ENVITED-X systems. +No retroactive changes to previous assets are required. ## References diff --git a/EVES/drafts/EVES-004/eves-004.md b/EVES/drafts/EVES-004/eves-004.md index 6e0dd31..8d3f1e0 100644 --- a/EVES/drafts/EVES-004/eves-004.md +++ b/EVES/drafts/EVES-004/eves-004.md @@ -1,6 +1,6 @@ --- eves-identifier: 004 -title: Roles and Responsibilities of EVES Editors +title: ENVITED-X Roles and Responsibilities of EVES Editors author: Carlo van Driesten (@jdsika) discussions-to: status: Draft @@ -110,6 +110,7 @@ This specification provides clarity on the editors' tasks, empowering the commun #### 4.2 Providing Technical Designs or Implementations - Authors and contributors are solely responsible for technical designs and reference implementations. +- Information about e.g designs and technical implementations are only exchanged for the purpose of defining the specification. #### 4.3 Advocating for Specific Proposals @@ -127,8 +128,9 @@ This specification provides clarity on the editors' tasks, empowering the commun #### 4.6 Promoting or Ensuring Adoption of EVES -- Editors are not tasked with promoting specific EVES or ensuring their adoption. -- Community members and stakeholders must drive the promotion and integration of Final EVES. +- Editors are not tasked with promoting specific EVES or ensuring their adoption. +- The adoption of EVES is the free choice of every community member. +- Community members and stakeholders are solely responsible to drive the promotion and integration of Final EVES. #### 4.7 Maintaining Approved EVES diff --git a/EVES/drafts/EVES-005/eves-005.md b/EVES/drafts/EVES-005/eves-005.md index d0c6052..a93d367 100644 --- a/EVES/drafts/EVES-005/eves-005.md +++ b/EVES/drafts/EVES-005/eves-005.md @@ -1,22 +1,27 @@ --- eves-identifier: 005 -title: Contract Negotiation Process -author: Felix Hoops (@jfelixh) -discussions-to: https://github.com/ASCS-eV/EVES/issues/ +title: ENVITED-X Contract Negotiation Process +author: Felix Hoops (@jfelixh), Carlo van Driesten (@jdsika) +discussions-to: status: Draft type: Process created: 2024-12-02 -requires: ["EVES-001"] +requires: ["EVES-001", "EVES-002", "EVES-003"] replaces: None --- ## Abstract -A market place requires processes for publishing assets, negotiating contracts, and settling these contracts as a basis for services and billing. We focus on the negotiation process, since it influences all of the other mentioned steps. This document is not a technical specification, but rather a high-level process description. Data standards and specific technology choices must be settled separately. +A market place requires processes for publishing assets, negotiating contracts, and settling these contracts as a basis for services and billing. +We focus on the negotiation process, since it influences all of the other mentioned steps. +This document is not a technical specification, but rather a high-level process description. +Data standards and specific technology choices must be settled separately. ## Motivation -Gaia-X specifications on the topic are high-level (refer to [this](https://docs.gaia-x.eu/technical-committee/architecture-document/24.04/other_concepts/#computational-contracts)) and existing implementations like the Eclipse Dataspace Connector's [negotiation](https://github.com/eclipse-dataspace-protocol-base/DataspaceProtocol/blob/main/negotiation/contract.negotiation.protocol.md) are complex. Beyond that, we have specific goals that are not fulfilled by any specification we are aware of at the time of writing: +Gaia-X specifications on the topic are high-level (refer to [this](https://docs.gaia-x.eu/technical-committee/architecture-document/24.04/other_concepts/#computational-contracts)). +Existing implementations like the Eclipse Dataspace Connector's [negotiation](https://github.com/eclipse-dataspace-protocol-base/DataspaceProtocol/blob/main/negotiation/contract.negotiation.protocol.md) are complex. +Beyond that, we have specific goals that are not fulfilled by any specification we are aware of at the time of writing: 1. Ensure that the market place can mandate the use of pre-approved contract templates to ensure fairness and collect proportional fees. 2. Finalize contracts in a way that makes them fully provable to third parties, including timestamp, to give legal security to participants. @@ -28,7 +33,9 @@ Gaia-X specifications on the topic are high-level (refer to [this](https://docs. ### 1. Stakeholders -The ENVITED-X market place _operator_ provides and maintains the market place infrastructure. The operator also acts as a trust anchor giving access and verifiable identities to participants. For these services, the operator collects fees from providers based on sales volume. +The ENVITED-X Data Space place _operator_ provides and maintains the market place infrastructure. +The operator also acts as a trust anchor giving access and verifiable identities to participants. +For these services, the operator collects fees from providers based on sales volume. The _provider_ is interested in selling an asset. @@ -37,10 +44,11 @@ The _consumer_ is interesting in buying an asset. ### 2. Initial Setup The operator must set up a smart contract that allows anyone to retrieve a set of acceptable contract templates, which should have the form of ODRL policies. - -The operator must run a _settlement service_ that can be used to settle contracts. Contract credentials are only considered valid once their hash has been submitted to this service, which publishes the hash (directly or indirectly) on a blockchain. - -We assume that the provider and consumer run a _negotiation service_ that consists of frontend and backend. It could be a part of other infrastructure, such as the dataspace connector. This services takes over communication between provider and consumer. +The operator must run a _settlement service_ that can be used to settle contracts. +Contract credentials are only considered valid once their hash has been submitted to this service, which publishes the hash (directly or indirectly) on a blockchain. +We assume that the provider and consumer run a _negotiation service_ that consists of frontend and backend. +It could be a part of other infrastructure, such as the dataspace connector. +This services takes over communication between provider and consumer. ### 3. Asset Setup @@ -51,27 +59,34 @@ The provider must register an asset as described in EVES-003. The consumer uses metadata search or similar services to identify an asset of interest, before he contacts the provider to negotiate a contract. 1. The consumer asks the provider for a contract offer (i.e., quote) for the asset. -2. The provider creates a contract offer referencing a contract template. This offer contains specific data, such as pricing and usage requirements. +2. The provider creates a contract offer referencing a contract template. + This offer contains specific data, such as pricing and usage requirements. 3. The provider sends the contract offer to the consumer in the form of a Verifiable Credential. -4. The consumer checks that the offer is correctly signed and that it references a valid contract template. The offer may not conflict with the template. +4. The consumer checks that the offer is correctly signed and that it references a valid contract template. + The offer shall not conflict with the template. 5. If the consumer accepts, he constructs a contract credential, which wraps the contract offer. 6. The consumer sends this contract credential back to the provider, to ensure that both parties have the full contract without involving a third party. -7. The provider validates the contract credential. In this step, the provider could also choose to ignore the contract. For example, if the offer has expired. +7. The provider validates the contract credential. + In this step, the provider could also choose to ignore the contract. + For example, if the offer has expired. 8. The provider sends the hash of the contract credential to the operator's settlement service. -9. The settlement service locally saves the hash and which provider sent it. Then, the service commits just the hash to the public blockchain. +9. The settlement service locally saves the hash and which provider sent it. + Then, the service commits just the hash to the public blockchain. 10. The consumer and provider monitor the blockchain to see if the contract has been settled. At this point, the contract is fully settled and the consumer can use the asset. ### 5. Fee Payment -On a regular basis, the providers send the accumulated fees to the operator. To ensure the fees are correctly calculated without publishing business statistics, a provider should construct a zero knowledge proof for the accumulated amount being correct based on the submitted hashes. +On a regular basis, the providers send the accumulated fees to the operator. +To ensure the fees are correctly calculated without publishing business statistics, a provider should construct a zero knowledge proof for the accumulated amount being correct based on the submitted hashes. ### 6. Limitations and Discussion -We assume that the provider and consumer have an interest in properly time-stamping their contract agreement. This interest ensures that the operator is aware of any transaction that may generate fees. - -Provider and consumer may add a status entry to their Verifiable Credentials to mark the contract or the offer in some way. This could be useful in the case of a legal dispute to give a contract a disputed status or even entirely revoke it. +We assume that the provider and consumer have an interest in properly time-stamping their contract agreement. +This interest ensures that the operator is aware of any transaction that may generate fees. +Provider and consumer may add a status entry to their Verifiable Credentials to mark the contract or the offer in some way. +This could be useful in the case of a legal dispute to give a contract a disputed status or even entirely revoke it. This negotiation process heavily limits data exposure, but some information beyond what what is exposed by necessity and design can still be learned: diff --git a/EVES/resources/eves-template.md b/EVES/resources/eves-template.md index 4172157..48bfdc2 100644 --- a/EVES/resources/eves-template.md +++ b/EVES/resources/eves-template.md @@ -1,6 +1,6 @@ --- eves-identifier: 00X -title: Name describing the EVES +title: Name describing the EVES, prefixed with "ENVITED-X " author: Name (@GitHub user) discussions-to: https://github.com/ASCS-eV/EVES/issues/ status: Draft diff --git a/README.md b/README.md index 3d8023e..2db227e 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,8 @@ The process on how to write, submit or change specifications in defined in [EVES | Number | Title | Type | Status | | ------ | ----- | ---- | ------ | -| [001](./EVES/drafts/EVES-001/eves-001.md) | ENVITED Ecosystem Specification Process | Process | Draft | +| [001](./EVES/drafts/EVES-001/eves-001.md) | ENVITED-X Ecosystem Specification Process | Process | Draft | | [002](./EVES/drafts/EVES-002/eves-002.md) | ENVITED-X Data Space Architecture Overview | Standards | Draft | -| [003](./EVES/drafts/EVES-003/eves-003.md) | ENVITED Asset Definition and Upload Process | Standards | Draft | -| [004](./EVES/drafts/EVES-004/eves-004.md) | ENVITED Roles and Responsibilities of EVES Editors | Process | Draft | +| [003](./EVES/drafts/EVES-003/eves-003.md) | ENVITED-X Asset Definition and Upload Process | Standards | Draft | +| [004](./EVES/drafts/EVES-004/eves-004.md) | ENVITED-X Roles and Responsibilities of EVES Editors | Process | Draft | +| [005](./EVES/drafts/EVES-005/eves-005.md) | ENVITED-X Contract Negotiation Process | Process | Draft |