Ir para o conteúdo

01 — Blockchain Layer Overview

Architectural role

Hyperledger Fabric is the only permanent storage for federated records in the HDT-AF core, as well as its trust and governance layer. It does not execute federated learning and never stores raw client data. Temporary artifact staging may be used while a round is processed, but it is not an archive and must be deleted after the corresponding ledger transaction is confirmed. Fabric records the durable, verifiable state of each experiment:

  • existence and version of an experiment contract;
  • identity and hash of the authorized training code;
  • acceptance or rejection by each participating client;
  • hashes of partitioned local datasets;
  • hashes of local updates per round;
  • result and quorum of each aggregation;
  • version, hash, and promotion decision of the global model.

These records form an immutable audit trail that allows any step of the experiment to be reconstructed, verified, and challenged without exposing sensitive data.

Why Hyperledger Fabric

Fabric was chosen over public alternatives (Ethereum, Polygon) for the following reasons:

Criterion Fabric Public blockchain
Identity control MSP with X.509 certificates per organization Public-key identity, with no institutional link
Privacy Channels and Private Data Collections restrict access by consortium Transactions visible by default on the public network
Performance Transactions finalized in seconds without proof of work Latency and cost vary with gas
Chaincode language Native Java — aligned with the project's Java-only decision Solidity (Ethereum) or other specific languages
Governance Permissioned consortium among partner institutions Full decentralization without a consortium

On-chain vs. off-chain principle

Fabric storage and replication have a cost, so payload sizes must be bounded and raw client data must remain local. Durable contracts, consent decisions, update/model vectors, metrics and provenance are committed to Fabric. Any off-chain copy required for transport, serialization or presentation is temporary staging and must be deleted only after ledger commit confirmation. Training code remains a separately managed source/deployment input outside the federated core; any runtime package copy must be temporary and must not become durable core state.

Global model / local update vector
    → SHA-256 hash still computed locally, for integrity verification
    → the vector itself (as CSV) + hyperparameters/metrics/provenance (as JSON)
      + hash + URI + version all recorded on Fabric (on-chain)
    → any transport copy in Artifact Experiment Service is temporary staging;
      delete it after the ledger commit is confirmed

Other artifacts needed during a round (for example serialized reports)
    → temporary staging only, bounded by size and retention
    → SHA-256 hash computed locally
    → durable metadata/evidence recorded on Fabric
    → staged copy deleted after successful ledger commit

What must be ON-CHAIN

Data Responsible chaincode
Experiment contract (version, hash, URI, coordinator, status) ExperimentContractSmartContract
Registered training code (hash, URI, signature, manifest, entrypoint) ExperimentContractSmartContract
Client acceptance or rejection (status, accepted hash, signature) ClientConsentSmartContract
Consent revocation ClientConsentSmartContract
Hash of the local dataset partitioned per client FederatedExperimentSmartContract
Preflight hash per round and client FederatedExperimentSmartContract
Local update — hash, weight vector (CSV), sample/positive counts, norm, local metric FederatedExperimentSmartContract (ClientUpdateAsset)
Aggregation result (report hash, quorum) FederatedExperimentSmartContract
Global model version — hash, URI, promotion decision, weight vector (CSV), round hyperparameters, training/evaluation metrics, aggregation provenance FederatedExperimentSmartContract (GlobalModelAsset)
Complete inference bundle — compressed .hdtmodel.zip, SHA-256, and manifest metadata FederatedExperimentSmartContract (InferencePackageAsset)
Chained audit events FederatedExperimentSmartContract

What must be OFF-CHAIN

Data Storage
Raw client data Local at data/{client_id}/{experiment_id}/
Raw client data Local at data/{client_id}/{experiment_id}; never copied to core storage
Temporary serialized artifacts during a round Ephemeral staging only; delete after ledger commit confirmation
Extensive operational logs Bounded observability stream; not permanent experiment state
Target for permanent federated state, including model/update vectors, accepted contract versions, consent and audit provenance Hyperledger Fabric only

Implementation status: the current ModelBackupService and ModelArtifactStore descriptions/code paths keep off-chain copies. They violate this target rule until changed to ephemeral staging with commit-aware deletion. The architecture requirement must not be read as a claim that those code paths have already been migrated. Migration must also remove durable references to deleted staging URIs and make model retrieval use the committed Fabric payload.

Hyperledger Fabric elements used

Fabric element Use in the architecture
Organizations Represent the researcher, clients, aggregator, and governance
MSP (Membership Service Provider) Defines trusted identities per organization
Certificate Authority Issues and revokes X.509 certificates
Peers Execute chaincodes and maintain the local ledger
Orderer Orders and finalizes transaction blocks
Channels Isolate experiments or consortiums — one channel per privacy scope
Private Data Collections Restrict sensitive metadata to subsets of organizations
Chaincodes Implement contract, consent, and audit logic

Security mechanisms

  • MSP: every transaction is signed by the issuing organization's certificate.
  • Endorsement policies: critical operations require endorsement from multiple organizations (e.g., creating a contract requires researcher + governance; registering a model requires aggregator + orchestrator).
  • Ledger immutability: no transaction can be altered retroactively.
  • Chaincode access control: state validations prevent invalid transitions and overwriting of evidence.
  • Channels: isolation between distinct experiments or consortiums.
  • Private Data Collections: for metadata that cannot be exposed to all peers.
  • Certificate revocation: compromised identities can be revoked without altering the history.

File structure

deploy/fabric/chaincode/federated-governance-java/
├── build.gradle                        # Gradle with shadow JAR; fabric-chaincode-shim:2.5.4 dependency
├── settings.gradle
└── src/main/java/br/ufma/lsdi/fabric/contracts/
    ├── ExperimentContractSmartContract.java   # Chaincode 1: contract lifecycle
    ├── ClientConsentSmartContract.java        # Chaincode 2: client consent
    ├── FederatedExperimentSmartContract.java  # Chaincode 3: round and model auditing
    ├── assets/
    │   ├── ExperimentContractAsset.java
    │   ├── TrainingCodeAsset.java
    │   ├── ClientConsentAsset.java
    │   ├── AuditEventAsset.java
    │   ├── DatasetEvidenceAsset.java
    │   └── GlobalModelAsset.java
    └── util/
        ├── Json.java          # JSON serialization with no external dependencies
        ├── LedgerConstants.java   # Statuses, object types
        ├── StateKeys.java         # World state composite keys
        └── Validation.java        # Input validations (required, hash, integer)

Build and packaging

# Build the fat JAR (shadow JAR)
cd deploy/fabric/chaincode/federated-governance-java
gradle shadowJar

# Package for Fabric (from the project root)
sh scripts/fabric-package-chaincode.sh
# → target/fabric/federated-governance-chaincode.tar.gz

The fabric-package-chaincode.sh script attempts to use the peer lifecycle chaincode package binary. If the peer is unavailable or the command fails, the script manually creates the package in the format expected by the Fabric lifecycle: metadata.json + code.tar.gz bundled into federated-governance-chaincode.tar.gz.

Environment variables for the peer binary

Variable Default Description
FABRIC_HOME blockchain/hyperledger-fabric on Google Drive Root directory of the Fabric binaries
FABRIC_PEER_BIN $FABRIC_HOME/bin/peer Full path to the peer binary
FABRIC_CHANNEL_NAME federated-channel Fabric channel where the chaincodes are installed
FABRIC_CHAINCODE_NAME federated-governance Name of the chaincode installed on the channel
FABRIC_FAIL_ON_ERROR true Fabric failures block operations in the only supported BLOCKCHAIN mode