Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Align exchanges with spec workflows #25

Open
2 tasks
jrhender opened this issue Jun 21, 2024 · 3 comments
Open
2 tasks

Align exchanges with spec workflows #25

jrhender opened this issue Jun 21, 2024 · 3 comments
Labels
spec alignment alignment to the VC API specification

Comments

@jrhender
Copy link
Contributor

jrhender commented Jun 21, 2024

The VC API spec has introduced a new workflows section: https://w3c-ccg.github.io/vc-api/#workflows-and-exchanges

This implementation has an exchanges features.

Aligning this implementation to the spec would:

  • Reduce confusion of users of the implementation (especially when the legacy exchanges text is removed)
  • Further the development of the spec by providing an implementation that is testing the use case suitability
  • Reduce the implementation's documentation burden by delegating documentation to the specification

Definition of done

Endpoint translation

Endpoint Purpose Currently Implemented Endpoint Updated VC API Spec Endpoint
Admin creates an exchange POST /exchanges POST /workflows & POST /exchanges
Admin retrieves the result of the exchange GET /exchanges/{exchangeId}/{transactionId} ??
Client retrieves the status of an exchange Reuse of POST /exchanges/{exchangeId}/{transactionId} GET /workflows/{localWorkflowId}/exchanges/{localExchangeId}
Client participates in an exchange POST /exchanges/{exchangeId} & POST /exchanges/{exchangeId}/{transactionId}
@jrhender jrhender added the spec alignment alignment to the VC API specification label Sep 24, 2024
@jrhender
Copy link
Contributor Author

jrhender commented Oct 3, 2024

I think an important piece of this is issue is to align how the existing ExchangeDefinition in the implementation with the new Create Workflow request body
Propose alignment details:

  1. Create a new CreateWorkflowRequestDto
    1. Add initialStep property as required
    2. Omit support for controller, authorization and credentialTemplates
    3. Add id property
    4. Add the steps object. For each step in the object:
      1. Omit the createChallenge and openId properties
      2. Omit support for the stepTemplate schema
      3. Keep the callback: CallbackConfigurationDto[]; property. This isn't included in the spec yet but there is discussion about adding it in the future Add callback url to exchanges? w3c-ccg/vc-api#347
      4. For the verifiablePresentationRequest property
        1. Reuse the query property from the ExchangeDefinition (i.e. the VpRequestQueryDto[] type)
        2. Reuse the interact property from the ExchangeDefinition (i.e. the ExchangeInteractServiceDefinitionDto[] type)
        3. Omit challenge. This will be generated automatically when returning the actual VPRs during an exchange
        4. Add domain property

@jrhender
Copy link
Contributor Author

jrhender commented Oct 3, 2024

Another key piece is how to modify the existing entities.
Note that a key idea that an exchange is an instance of a workflow.
Proposed approach:

  1. Rename transactionEntity to exchangeStepEntity
  2. Split the exchangeEntity into two entities: workflowEntity and exchangeEntity. Also create a new workflowStep type/entity

Workflow Entity

  • Properties:
    • workflowId
    • workflowSteps
    • callback
  • Methods:
    • getFirstStep. No parameters, returns WorkflowStepDefinitionDto
    • getNextStep(currentStep: string): returns WorkflowStepDefinitionDto

WorkflowStep Entity

Note: workflowStep could be a new entity, but it could also be a simple Type and persisted as simple-json

  • Properties:
    • interactServiceDefinitions -> moved from exchange
    • query -> moved from exchange

Exchange Entity

  • Properties:
    • exchangeId
    • ttl -> from the spec
    • state -> from the spec
    • step -> from the spec
    • stepLog -> an array of exchangeSteps that the exchange has gone through
    • we can omit ttl, sequence variables for now. variables can also be omitted from the request.
  • Methods:
    • The existing start method should be on the exchangeEntity as I think it is essentially creating a new exchangeStep. It should be renamed to participate

ExchangeStep Entity

This is a rename of the TransactionEntity

@jrhender
Copy link
Contributor Author

jrhender commented Oct 9, 2024

Here is how I envision how I envision some of the sequences with the above entities would look.

Entity Design

The Workflow and Exchange entities are separate aggregates.
So, as I see it, they have separate consistency boundaries and a transaction should only update one of them.
The ExchangeSteps are under the Exchange aggregate, so they are persisted by persisting the whole Exchange.

Workflows have methods (getFirstStep and getNextStep) that output a WorkflowStep value object that can be passed to ExchangeEntities to help the Exchange determine it's next step.

Loading
graph TD
    subgraph Workflow Aggregate
        WorkflowEntity[WorkflowEntity]
    end
    
    subgraph Exchange Aggregate
        ExchangeEntity[ExchangeEntity]
        ExchangeStepEntity[ExchangeStepEntity]
        ExchangeEntity --> ExchangeStepEntity
    end

Create a new Exchange

This is after the workflow has been created already and someone calls POST /workflows/{localWorkflowId}/exchanges

Loading
sequenceDiagram
participant ws as WorkflowService
participant wr as WorkflowRepository
participant er as ExchangeRepository
participant we as WorkflowEntity
participant ee as ExchangeEntity

ws ->> wr: retrieve workflow entity
ws ->> we: call WorkflowEntity.getFirstStep
we -->> ws: return WorkflowStep Value Object
ws ->> ee: call ExchangeEntity constructor, passing the WorkflowStep
ee ->> ee: ExchangeEntity constructor includes new ExchangeStepEntity
ee -->> ws: return new ExchangeEntity
ws ->> er: persist new ExchangeEntity (which also persists the ExchangeStep)

Participate in Exchange

This is triggered by a call to POST /workflows/{localWorkflowId}/exchanges/{localExchangeId}

Loading
sequenceDiagram
participant ws as WorkflowService
participant wr as WorkflowRepository
participant er as ExchangeRepository
participant we as WorkflowEntity
participant ee as ExchangeEntity
participant ese as ExchangeStepEntity

ws ->> er: retrieve exchange entity
ws ->> wr: retrieve workflow entity
ws ->> we: call getNextStep(exchangeEnity.currentStep)
we -->> ws: return next WorkflowStep
ws ->> ee: call participate(nextWorkflowStep, presentation, verifier)
ee ->> ese: call processPresentation
ee ->> ee: based on processing result, create new step in exchange
ws ->> er: persist updated ExchangeEntity (which also persists all the ExchangeSteps)
ee ->> ese: call getStepResponse()
ee -->> ws: return ExchangeResponse

Get Exchange Response

This is a response to a call to GET /workflows/{localWorkflowId}/exchanges/{localExchangeId}.
Note that this endpoint isn't in the spec yet, but it is proposed here: w3c-ccg/vc-api#429

Loading
sequenceDiagram
participant ws as WorkflowService
participant wr as WorkflowRepository
participant er as ExchangeRepository
participant we as WorkflowEntity
participant ee as ExchangeEntity
participant ese as ExchangeStepEntity

ws ->> er: retrieve exchange entity
ws ->> wr: retrieve workflow entity
ws ->> ee: call getResponse()
ee ->> ese: call getStepResponse()
ee -->> ws: return ExchangeResponse

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
spec alignment alignment to the VC API specification
Projects
None yet
Development

No branches or pull requests

1 participant