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 |