Consider adding storageRef field to DataProvenance DataRecord

[crtahlin]

Context

Currently DataProvenance.registerData() anchors a single bytes32 dataHash (e.g. SHA256 of content). There is no way to associate a secondary reference such as a Swarm storage hash with the same record.

Use case: When uploading content to Swarm, you get a Swarm reference hash back. You want to register both the content's SHA256 and the Swarm reference where it's stored, linked together on-chain.

Current workaround

Use recordTransformation to link the two hashes, but this is semantically incorrect — a storage location is not a transformation.

No other contract in the set (ConsentAuditLog, ConsentProxy, DataAccessControl, DataDeletion, KantaraConsentReceipt, PurposeRegistry) handles this either.

Proposal

Add a bytes32 storageRef (or bytes32[] storageRefs for multiple storage backends) to the DataRecord struct and extend registerData / registerDataFor to accept it.

Things to consider

• Should it be a single bytes32 or an array for multiple storage locations?
• Should there be an updateStorageRef function to add/change storage refs after registration?
• Impact on gas costs
• Whether this belongs in DataProvenance or a separate StorageRegistry contract

[crtahlin]

Additional consideration: reverse lookup

Solidity mappings only work by key. With mapping(bytes32 => DataRecord), records are only queryable by dataHash. Adding a storageRef field alone would not make records queryable by storage reference.

To support lookup in both directions, a reverse mapping would be needed:

mapping(bytes32 => bytes32) public storageRefToDataHash;

Populated during registerData, this allows: Swarm hash → content hash → full record. Same pattern already used for transformationParents. Trade-off is slightly higher gas on write.

[crtahlin]

Use case from dataprovenance-app (datafund/dataprovenance-app#90)

We need to anchor both a file's SHA-256 hash and its Swarm storage reference, with bidirectional lookup. This enables verification by either value — dropping a file (SHA-256) or pasting a Swarm reference.

Proposed contract API

// Existing — unchanged, backwards compatible
function registerData(bytes32 dataHash, string dataType)

// New — anchors hash with linked storage reference
function registerWithReference(bytes32 dataHash, bytes32 storageRef, string dataType)

Required mappings

mapping(bytes32 => bytes32) public hashToReference;   // sha256 → swarmRef
mapping(bytes32 => bytes32) public referenceToHash;    // swarmRef → sha256

Scenarios to support

Scenario	Call	Lookup by hash?	Lookup by ref?
Hash only (current, no change)	registerData(hash, type)	Yes	No
Hash + storage ref (new)	registerWithReference(hash, ref, type)	Yes + ref	Yes + hash

Requirements

• registerData must remain unchanged (backwards compatible)
• registerWithReference populates both mappings
• Both dataHash and storageRef should be independently queryable via getDataRecord() or a new getter
• If storageRef is bytes32(0), behave like registerData

Context

• dataprovenance-app records a file's SHA-256 hash + metadata to Swarm, gets a Swarm reference back
• Currently only the SHA-256 is anchored on-chain
• Users want to verify by dropping a file (SHA-256 lookup) OR by pasting a receipt URL (Swarm reference lookup)
• Without the link, one of these paths breaks

[crtahlin]

Implementation Plan

Design Decisions

• Single bytes32 storageRef on DataRecord (not an array)
• Reverse mapping mapping(bytes32 => bytes32) public storageRefToDataHash for bidirectional lookup
• Function overloading for backward compatibility — registerData(bytes32, string, bytes32) alongside existing registerData(bytes32, string), both delegate to internal _registerData
• New event StorageRefLinked(bytes32 indexed dataHash, bytes32 indexed storageRef) — keeps existing DataRegistered unchanged
• No updateStorageRef in v1

Contract Changes

File	Changes
DataProvenance.sol	Add storageRef to struct, reverse mapping, _registerData internal helper, overloaded registerData/registerDataFor/batchRegisterData, getDataHashByStorageRef getter
interfaces/IDataProvenance.sol	Mirror struct + new function signatures + event
IntegratedConsentProvenanceSystem.sol	Overloaded registerDataWithConsent/registerDataForWithConsent that forward storageRef

No changes needed to: DataAccessControl, DataDeletion, ConsentReceipt, KantaraConsentReceipt, ConsentProxy, PurposeRegistry, ConsentAuditLog.

Tests to Add

File	Tests
DataProvenance.test.ts	Register with storageRef, verify in record, bidirectional lookup, revert on duplicate storageRef, revert when storageRef==dataHash, delegated registration with storageRef, backward compat
IntegratedConsentProvenanceSystem.test.ts	registerDataWithConsent with storageRef, verify propagation
Security.test.ts	StorageRef collision attacks, zero-ref not stored in mapping
Integration.test.ts	End-to-end: register → lookup by storageRef → verify

Docs to Update

• README.md, CLAUDE.md, deployments.md (auto), dist/abis/ (auto)
• examples/10-swarm/ — update anchor example, add bidirectional lookup example

Deployment

Fresh deploy required (not upgradeable). Old Base Sepolia addresses → "Previous Deployments".

Downstream Repos (issues to file)

Repo	What
datafund/swarm_provenance_SDK	ABI, optional storageRef on anchor()/anchorFor(), getDataHashByStorageRef()
datafund/swarm_provenance_MCP	ABI, optional storage_ref on anchor_hash, reverse lookup tool
datafund/swarm_provenance_CLI	ABI, contract wrapper, tests
datafund/dataprovenance-app	Depends on SDK; pass storageRef when anchoring

Gas Impact

Minimal — one extra SSTORE (~20k gas) when storageRef is provided. Zero cost when omitted.

[crtahlin]

Downstream issues filed

Implementation is done on the development branch. Downstream repos need ABI + SDK updates after deployment:

• SDK: Support storageRef in anchor/anchorFor swarm_provenance_SDK#90
• MCP: Support storageRef in anchor_hash tool swarm_provenance_MCP#133
• CLI: Support storageRef in chain anchoring swarm_provenance_CLI#116
• App: datafund/dataprovenance-app#91

[crtahlin]

Follow-up: setStorageRef (issue #11)

During implementation, we identified that recordTransformation and recordMergeTransformation create new records without storageRef support. Rather than adding overloads to every record-creating function, we added setStorageRef(bytes32 _dataHash, bytes32 _storageRef) — a set-once function that allows attaching a storage reference to any existing record after creation.

Key property: immutable after first write. Once a storageRef is set (either at registration or via setStorageRef), it cannot be changed.

Typical workflow for transformed data:

1. recordTransformation(original, newHash, "anonymized") — creates record, no storageRef
2. Upload transformed data to Swarm — get Swarm reference
3. setStorageRef(newHash, swarmRef) — permanently link the two

This is implemented on the development branch and will be included in the next deployment.