# scross

**Repository Path**: xbcdbc/scross

## Basic Information

- **Project Name**: scross
- **Description**: SCROSS is an auditable cross-chain storage protocol that combines PDP-based data auditing, semantic verification, encrypted cloud storage, and Wecross HTLC transactions. It provides secure file upload
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-22
- **Last Updated**: 2026-10-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Blockchain, PDP, cross-chain, Data-Integrity-Auditing

## README

# SCROSS

SCROSS is an implementation of an auditable cross-chain storage protocol. The public runtime path is:

```text
Console -> KGC setup and key generation
        -> encrypted upload and PDP metadata registration
        -> Cloud block and authenticator storage
        -> TPA challenge, proof retrieval, and verification
        -> WeCross HTLC proposal, lock, unlock, and Cloud transfer
        -> authenticated ECDH, HKDF, EDEK exchange, and DEK recovery
```

The repository keeps the `pdp/newscross` protocol implementation, the KGC/Cloud/TPA services, the WeCross Console integration, the Solidity contracts, and the code used to validate this path.

## License

SCROSS source code is released under the [MIT License](./LICENSE). The WeCross Console components under `wecross-console/` retain their original [Apache License 2.0](./wecross-console/LICENSE). Attribution details are available in [NOTICE](./NOTICE).

## Requirements

- JDK 11
- Maven 3.8 or newer
- Bash, `curl`, `awk`, `dd`, and `shasum`
- A running WeCross Router and the deployed contracts for the real cross-chain path

Default service ports are KGC `7001`, Cloud `7002`, and TPA `7003`.

## Configuration

Create the ignored local configuration file once:

```bash
cp .env.example .env
```

Edit `.env` with local paths, service addresses, WeCross resource names, and credentials. Do not commit `.env`. Repository scripts load it automatically, and Spring services import it when started from the repository root.

Set `SCROSS_JAVA_HOME` in `.env` when multiple JDK versions are installed; this project requires Java 11 because the semantic validation dependency is not compatible with newer JDKs.

The KGC creates `.cross/kgc/system.yml` on first start. This file contains private system material and is ignored. Console key files, public-parameter caches, Cloud storage, logs, and runtime results are kept under `.cross/` and are local-only.

## Build

```bash
mvn -q -DskipTests package
```

Run the focused protocol tests:

```bash
mvn -q -pl cross-over-common -am \
  -Dtest=EcdhKeyAgreementUtilsTest,HkdfSha256UtilsTest,Sm4GcmCryptoUtilsTest,ScrossProtocolDemoTest \
  -Dsurefire.failIfNoSpecifiedTests=false test
```

Run the service HTTP integration tests:

```bash
bash scripts/run_http_service_evaluation.sh
```

## Run the real protocol path

Initialize the WeCross and two-blockchain environment before starting the real protocol:

```text
./docs/blockchain-environment-assessment.md
```

Start the three local services with the project configuration:

```bash
bash scripts/start_services.sh
```

The script writes service logs and PID files below `.cross/`. Stop the services with:

```bash
bash scripts/stop_services.sh
```

Start the Console in a second terminal:

```bash
bash scripts/run_console.sh
```

Set the chain-local resource before uploading a file:

```dotenv
SCROSS_WECROSS_RESOURCE_PATH=payment.bcos1.FileTagStorage
```

Use `payment.bcos3.FileTagStorage` for the participant chain. The deployed HTLC resources are `payment.bcos1.FileTagStorageHTLC` and `payment.bcos3.FileTagStorageHTLC`.

Inside the Console, the normal user path is:

```text
login <user> <local-password>
kgc init
kgc keygen
kgc register
uploadFile <chainPath> <fileId> <filePath> [ruleText]
auditChallenge <fileId>
```

`uploadFile` encrypts the file with SM4-GCM, stores the local key envelope, derives PDP authenticators from the ciphertext, uploads ciphertext blocks to Cloud, registers metadata, and persists the chain record. `auditChallenge` calls TPA, which obtains the Cloud proof and verifies the pairing equation.

The HTLC path is implemented by `HTLCImpl` and the `FileTagStorageHTLC` contracts. It performs proposal creation, dual-chain locking, audit-gated unlock, Cloud ownership transfer, authenticated ECDH, HKDF session-key derivation, signed EDEK exchange, and local DEK recovery. `ruleUpdate` and `recoverHTLC` are available for the corresponding rule-update and interrupted-session paths.

## Repository layout

```text
cross-over-common/       Shared cryptography, DTOs, PDP entities, and protocol code
audit-kgc-service/       KGC REST service
cloud/                   Cloud storage, proof generation, and key-exchange sidecar
tpa/                     TPA audit service
wecross-console/         Console commands and real-chain protocol orchestration
contract/                Solidity contracts used by the runtime path
cross-over-common/src/main/java/pdp/
  newscross/experiment/  Current SCROSS experiment implementations
  zhang_et_al_2023/experiment/
  cui_et_al_2025/experiment/
  han_et_al_2024/experiment/
cross-over-common/src/main/resources/experiment/
  newscross/<experiment>/run-*/     CSV, PDF, EPS, and runtime results
  newscross/<experiment>/plot.py    Experiment plotting script
experiments/real-chain-session/       Real-chain E2E test and target server
scripts/                 Environment loading, service lifecycle, and validation scripts
docs/                    Runtime guidance, workflow notes, and architecture records
```

## Where Go to Next
- [SCROSS protocol workflow](./docs/real-chain-protocol-workflow.md)
- [Notary cross-chain workflow](./docs/notary-protocol-workflow.md)
- [Blockchain environment setup](./docs/blockchain-environment-assessment.md)
- [PDP experiments](./docs/pdp-experiments.md)