Data transfer

After a contract negotiation reaches FINALIZED, the consumer can initiate a data transfer. RUN-DSP implements the IDSA Dataspace Protocol transfer process state machine.

States

stateDiagram-v2
    [*] --> REQUESTED : Consumer requests transfer
    REQUESTED --> STARTED : Provider starts transfer
    STARTED --> COMPLETED : Transfer completed
    STARTED --> SUSPENDED : Either party suspends
    SUSPENDED --> STARTED : Either party resumes
    STARTED --> TERMINATED : Either party
    SUSPENDED --> TERMINATED : Either party
    COMPLETED --> [*]
    TERMINATED --> [*]

Download (pull flow)

The consumer application requests download coordinates from RUN-DSP via gRPC. RUN-DSP negotiates the transfer with the provider over DSP, then returns a signed URL and auth token. The consumer retrieves the file directly from the provider's storage endpoint and signals completion back to RUN-DSP.

sequenceDiagram
    participant A as Consumer application
    participant CR as Consumer RUN-DSP
    participant PR as Provider RUN-DSP
    participant B as Provider backend
    participant S as Storage

    A->>CR: gRPC — getProviderDatasetDownloadInformation<br/>{ provider_url, dataset_id }
    CR->>PR: DSP transfer request (REQUESTED)
    PR->>B: gRPC — request download URL for dataset
    B-->>PR: Signed URL + auth token
    PR->>CR: DSP transfer start with PublishInfo<br/>{ url, authType, token, transferId } (STARTED)
    CR-->>A: PublishInfo { url, authType, token, transferId }
    A->>S: HTTP GET — download file<br/>Authorization: <token>
    S-->>A: File bytes
    A->>CR: gRPC — signalTransferComplete(transferId)
    CR->>PR: DSP transfer completion (COMPLETED)

Upload (push flow)

The consumer application requests upload coordinates from RUN-DSP via gRPC. RUN-DSP negotiates the transfer with the provider, then returns an upload URL and auth token. The consumer posts the file directly to the provider's storage endpoint and signals completion back to RUN-DSP.

sequenceDiagram
    participant A as Consumer application
    participant CR as Consumer RUN-DSP
    participant PR as Provider RUN-DSP
    participant B as Provider backend
    participant S as Storage

    A->>CR: gRPC — getProviderDatasetUploadInformation<br/>{ provider_url, dataset_id }
    CR->>PR: DSP transfer request (REQUESTED)
    PR->>B: gRPC — request upload URL for dataset
    B-->>PR: Signed URL + auth token
    PR->>CR: DSP transfer start with PublishInfo<br/>{ url, authType, token, transferId } (STARTED)
    CR-->>A: PublishInfo { url, authType, token, transferId }
    A->>S: HTTP POST multipart/form-data<br/>Authorization: <token>
    S-->>A: 200 OK
    A->>CR: gRPC — signalTransferComplete(transferId)
    CR->>PR: DSP transfer completion (COMPLETED)

Transfer states

From	To	Actor	DSP endpoint
—	REQUESTED	Consumer	provider.dsp/transfers/request
REQUESTED	STARTED	Provider	consumer.dsp/:callback/transfers/:consumerPID/start
STARTED	COMPLETED	Consumer	consumer.dsp/transfers/:providerPID/completion
STARTED	SUSPENDED	Either	suspension endpoint
SUSPENDED	STARTED	Either	start endpoint
*	TERMINATED	Either	termination endpoint