Skip to content

Chaincode-Specification.md

Latest commit

 

History

History
92 lines (76 loc) · 3.55 KB

Chaincode-Specification.md

File metadata and controls

92 lines (76 loc) · 3.55 KB
Raw

Industrial Evidence Chain — Smart Contract (Chaincode) Specification

1. Smart Contract Overview

The EvidenceContract smart contract is implemented in Node.js 18 utilizing the fabric-contract-api (v2.5) framework. It encapsulates all business logic governing evidence registration, state queries, immutability assertions, and historical audit queries on the Hyperledger Fabric ledger.

  • Contract Path: blockchain/chaincode/evidence-contract/lib/evidenceContract.js
  • Smart Contract Class: EvidenceContract extends Contract
  • State Key Schema: EVIDENCE_<evidence_id> (e.g., EVIDENCE_f47ac10b-58cc-4372-a567-0e02b2c3d479)

2. Smart Contract Methods

2.1 InitLedger(ctx)

  • Description: Initializes the world state with baseline seed records.
  • Parameters: None.
  • Returns: JSON confirmation.

2.2 RecordEvidence(ctx, evidenceId, assetCode, evidenceHash, timestamp, submitterId)

  • Description: Anchors a new cryptographic evidence digest onto the ledger.
  • Parameters:
    • evidenceId (string, UUIDv4): Unique identifier of the evidence record.
    • assetCode (string): Code of the equipment (e.g., MACHINE-001).
    • evidenceHash (string, 64 hex chars): SHA-256 canonical digest.
    • timestamp (string, ISO-8601 UTC): Creation timestamp.
    • submitterId (string, UUIDv4): Submitter identifier.
  • Validation:
    • Validates that evidenceHash is exactly 64 hexadecimal characters (/^[a-fA-F0-9]{64}$/).
    • Asserts that key EVIDENCE_<evidenceId> does not already exist (prevents overwriting or duplicate anchors).
  • State Mutation: Writes state buffer to CouchDB world state:
{
  "docType": "evidence",
  "evidenceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "assetCode": "MACHINE-001",
  "evidenceHash": "5285fb70c383f23a9d9e6e8eebf82b8b9310bfbaae9ea2cf4b64f4ecf9ce152c",
  "timestamp": "2026-09-04T10:00:00Z",
  "submitterId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "txId": "tx-8b77a06f30a94488b394143419bb60b4",
  "blockTimestamp": "2026-09-04T10:06:12Z"
}
  • Events Emitted: EvidenceAnchored with payload { evidenceId, assetCode, evidenceHash }.

2.3 GetEvidence(ctx, evidenceId)

  • Description: Retrieves the immutable state record for an evidence ID.
  • Parameters: evidenceId (string).
  • Returns: Serialized JSON evidence object. Throws 404 Evidence does not exist if not found.

2.4 VerifyEvidence(ctx, evidenceId, candidateHash)

  • Description: Performs on-chain verification comparing a candidate SHA-256 hash against the stored ledger hash.
  • Parameters:
    • evidenceId (string)
    • candidateHash (string, 64 hex chars)
  • Returns:
{
  "evidenceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "isValid": true,
  "blockchainHash": "5285fb70c383f23a9d9e6e8eebf82b8b9310bfbaae9ea2cf4b64f4ecf9ce152c",
  "candidateHash": "5285fb70c383f23a9d9e6e8eebf82b8b9310bfbaae9ea2cf4b64f4ecf9ce152c",
  "match": true,
  "timestamp": "2026-09-04T10:00:00Z"
}

2.5 GetEvidenceHistory(ctx, evidenceId)

  • Description: Invokes ctx.stub.getHistoryForKey(key) to retrieve the full modification timeline and cryptographic block references for the key.
  • Returns: Array of historical snapshots with transaction IDs, timestamps, and deletion flags.

2.6 QueryEvidenceByAsset(ctx, assetCode)

  • Description: Executes a CouchDB JSON query against the state index:
{
  "selector": {
    "docType": "evidence",
    "assetCode": "MACHINE-001"
  }
}
  • Returns: Array of all evidence records anchored for the specified asset.