Provenance API Reference¶
Nevermined Smart Contracts implement the W3C Provenance specification allowing to register on-chain all the provenance information, digital signatures and fingerprints allowing to make use of an open, transparent and unique source of truth for any data ecosystem where multiple parties need to collaborate in a common goal.
The complete Nevermined Provenance architecture can be found in the Provenance Spec.
This module allows to register Provenance events associated to assets. Also allows to retrieve all the assets provenance track previously registered.
Registering Provenance¶
All the provenance events are registered on-chain via the Provenance contract. All the individual provenance events have to be associated to a Provenance ID
. This ID is a unique identifier that can be used later on to retrieve information about a specific event.
Registering provenance generation¶
Generation
is the completion of production of a new entity by an activity. This entity did not exist before generation and becomes available for usage after this generation.
Nevermined encapsulate every entity to be managed using Decentralized Identifiers (DID)
that are registered via the DIDRegistry
Smart Contract.
This contract registers automatically the provenance generation event when an asset is created. So this function is not exposed as part of the API, but is referenced here for clarity.
You can find more details of this in the Provenance Specs
Registering provenance derivation¶
Derivation
is a transformation of an entity into another, an update of an entity resulting in a new one, or the construction of a new entity based on a pre-existing entity.
This function allows to register a provenance derivation event when a new asset is created as a result of some other asset. The function parameters are:
provenanceId
the Provenance IDnewEntityDid
Identifier of the new asset derived as a result of the activityusedEntityDid
Identifier of the asset used for deriving a new asset as a result of the activityagentId
Public address of the user/agent associated with the actionactivityId
Identifier of the activity doing the derivation actionattributes
Optional attributes associated with the action
Example:
wasDerivedFrom("999", "did:nv:1234", "did:nv:5678", 0xa1a1, "activity creating asset", "+ information")
You can find more details of this function in the Provenance Specs
Registering provenance utilization¶
Usage
is the beginning of utilizing an entity by an activity. Before usage, the activity had not begun to utilize this entity and could not have been affected by the entity.
The function parameters are:
provenanceId
the Provenance IDdid
Identifier of the asset associated to the activityagentId
Public address of the user/agent associated with the actionactivityId
Identifier of the activity doing the usage actionattributes
Optional attributes associated with the action
Example:
used("999", "did:nv:1234", 0xa1a1, "using activity", "additional information")
You can find more details of this function in the Provenance Specs
Registering provenance association¶
Association
is an assignment of responsibility to an agent for an activity, indicating that the agent had a role in the activity.
This function allows to register a provenance association event to an asset. The function parameters are:
provenanceId
the Provenance IDdid
Identifier of the asset associated to the activityagentId
Public address of the user/agent associated with the actionactivityId
Identifier of the activity doing the association actionattributes
Optional attributes associated with the action
Example:
wasAssociatedWith("999", "did:nv:1234", "ac1", "additional information")
You can find more details of this function in the Provenance Specs
Registering provenance delegation¶
Delegation
is the assignment of authority and responsibility to an agent (by itself or by another agent) to carry out a specific activity as a delegate or representative, while the agent it acts on behalf of retains some responsibility for the outcome of the delegated work.
The function parameters are:
provenanceId
the Provenance IDdid
Identifier of the asset associated to the activitydelegateAgentId
Public address of the user/agent delegated by theresponsibleAgentId
responsibleAgentId
Public address of the user/agent responsible of thedid
activityId
Identifier of the activity doing the association actionsignature
Signature of theprovenanceId
provided by thedelegatedAgentId
. This will work as proof of agreement between the delegate and the responsible about a specific provenance action.attributes
Optional attributes associated with the action
Example:
actedOnBehalf("999", "did:nv:1234", 0xa1a1, 0xb2b2, "ac1", "s1gnatureeeee", "additional information")
You can find more details of this function in the Provenance Specs
Retrieving Provenance information¶
Search Provenance events related to an asset¶
When a new provenance event is recorded on-chain, an event is emitted including some information.
This function searches across all the ProvenanceAttributeRegistered
events related with a specific DID. Parameters:
did
Identifier of the asset we are looking to search provenance events
Example:
getDIDProvenanceEvents("did:nv:1234")
Search Provenance events related to an asset¶
When a new provenance event is recorded on-chain, an event is emitted including some information.
This function searches for specific provenance events methods (used
, wasGeneratedBy
, etc.) given a DID. Parameters:
method
- Reference to the W3C Provenance method event we are going to search. This parameter is anunsigned int
from0
to15
. See more here in the Smart Contract implementation.did
Identifier of the asset we are looking to search provenance events
Example:
getProvenanceMethodEvents(0, "did:nv:1234")
Get Provenance Entry¶
Get from the on-chain Provenance registry the information about one provenance event, given a provenance id. Parameters:
provenanceId
Provenance Identifier
Example:
getProvenanceEntry("049320943")
Get Provenance Owner¶
Get from the on-chain Provenance registry the information about who create the provenance entry given a provenance id. Parameters:
provenanceId
Provenance Identifier
Example:
getProvenanceOwner("049320943")
Managing Provenance Delegates¶
The provenance delegates are accounts that have the ability to register provenance events associated to an asset/entity (Decentralized Identifier - DID) on behalf of the owner. This is helpful in some situations where a user creates a new asset, and later can delegate to a third party to make some actions on an asset and in extension to register provenance events associated to that. The following functions describe how to manage the delegates regarding to DIDs.
Add a provenance delegate to a DID¶
It associates a new user as a delegate to an existing DID. Parameters:
did
Identifier of the asset where the delegate will be addeddelegatedAccount
Public address of the user associated as delegate to thedid
Example:
addDIDProvenanceDelegate("did:nv:1234", 0x1234)
Remove a provenance delegate from a DID¶
It removes an existing delegate of a DID. Parameters:
did
Identifier of the asset where the delegate will be removeddelegatedAccount
Public address of the user to remove as delegate to thedid
Example:
removeDIDProvenanceDelegate("did:nv:1234", 0x1234)
Is an user a provenance delegate?¶
Returns true or false if the user account provided is an existing delegate for an existing DID. Parameters:
did
Identifier of the assetdelegatedAccount
Public address of the user
Example:
isProvenanceDelegate("did:nv:1234", 0x1234)