Nevermined Assets API¶
Every entity object in Nevermined is encapsulated in an asset. Typically the abstract things like datasets, algorithms, services, workflows, etc. But technically can abstract any entity with services provided by an user to the rest network under some conditions. Any asset has 2 main components:
- A Decentralized Identifier or DID. A unique id that reference the asset. This is recorded on-chain when the asset is registered in a Nevermined network
- Metadata. A DID Document describing the asset and the services (access, compute, etc.) associated to that asset. This is recorded off-chain.
An on-chain DID can be used to resolve the metadata associated to it. You can find more information about the implementation of the SEAs and the services associated to Nevermined assets in the access Spec and the compute Spec.
Assets Management¶
Create an asset¶
It registers a new asset on Nevermined. It Creates a new DID, registering it on-chain through DIDRegistry
contract and off-chain in Metadata.
Parameters:
metadata
the metadata describing the asset (full metadata specification)publisherAccount
Public address of the account publishing the assetproviders
List of public addresses that can act on behalf of the asset publisher, typically for providing some services like access associated to itauthorization
Type of encryption used to validate authorization (PSK_RSA
,PSK_ECDSA
,SecretStore
)activityId
Provenance identifier of the activity doing the creation actionattributes
Optional attributes associated with the provenance creation
Example:
create("{ddo metadata}", 0xaabb, [0xccdd], "PSK_RSA", "creation", "+ attributes")
Create a compute service¶
It registers a new asset on Nevermined with a compute service associated to it. This function creates a new DID, registering it on-chain through DIDRegistry
contract and off-chain in Metadata.
Parameters:
metadata
the metadata describing the asset (full metadata specification)publisherAccount
Public address of the account publishing the assetproviders
List of public addresses that can act on behalf of the asset publisher, typically for providing some services like access associated to itauthorization
Type of encryption used to validate authorization (PSK_RSA
,PSK_ECDSA
,SecretStore
)activityId
Provenance identifier of the activity doing the creation actionattributes
Optional attributes associated with the provenance creation
Example:
createCompute("{ddo metadata}", 0xaabb, [0xccdd], "PSK_RSA", "creation", "+ attributes")
Order an asset¶
This function orders an Asset represented by a DID. It implies to initialize a Service Agreement on-chain between publisher and consumer. For lower level details you can take a look at access Specs.
As a result of an order
the function will return an agreementId
. This unique identifier about the Service Agreement just created can be used for further consumption of the access or compute service associated to it.
Parameters:
did
Identifier of the asset to orderindex
The service index of the agreement in the DDO to orderconsumerAccount
The Public address of the consumer account executing the order
Example:
order("did:nv:1234", 0, 0xaabb)
Download assets¶
This function downloads an Asset previously ordered (using the order
function).
Parameters:
agreementId
Identifier of the service agreement between the consumer and the publisherdid
Identifier of the asset to downloadindex
The service index to theaccess
service in the DDO to downloadpath
Destination folder where the asset files will be downloaded
Example:
download("8594385934", "did:nv:1234", 0, 0xaabb, "/path/to/destination")
Execute¶
This function executes a compute service of an Asset previously ordered (using the order
function).
Parameters:
agreementId
Identifier of the service agreement between the consumer and the publisherdid
Identifier of the asset to executeindex
The service index to thecompute
service in the DDO to executeworkflowDid
Identifier of the compute workflow to execute
Example:
execute("8594385934", "did:nv:1234", 0, 0xaabb, "did:nv:ccdd")
Transfer asset ownership¶
It transfer the on-chain ownership of one asset from the original owner to a different account.
Parameters:
did
Identifier of the asset to executenewAccountOwner
The Public address of account belonging to the new owner
Example:
transferOwnership("did:nv:1234", 0xddee)
Fetch assets associated information¶
This functions allow retrieve information related with assets. Assets information can be in two different places:
- On-chain. As part of the assets registry (
DIDRegistry
). There is stored thedid
and the url resolving to thedid document
orddo
. - Off-chain. As part of marketplaces, the metadata api services keep all the metadata information (in
ddo
format)
Resolve a DID into a DDO¶
A Nevermined network is composed by only one source of truth, the decentralized logic and storage provided by the blockchain and the Smart Contracts. A part of that, the network can be composed by many different marketplaces or metada repositories. This function resolves a did
existing in the unique source of truth (blockchain) into the ddo
(metadata) that can be stored in any of the multiple metadata servers existing in a Nevermined network deployment.
This function will return the metadata of an asset in DDO format. More information about the contents of this document can be found in the metadata specification page.
Parameters:
did
Identifier of the asset to resolve in a DDO that is off-chain
Example:
resolve("did:nv:1234")
Search for assets¶
This function search in a metadata api instance all the DDO that match the search criteria. This function will return a list of assets metadata matching the criteria. Parameters:
text
the search querysort
Key or list of keys to sort the resultoffset
Number of records per pagepage
Page showed
Example:
search("weather in Berlin", "price", 0, 1)
Get assets owned by an account¶
This function retrieves the list of assets owned by an account. Parameters:
account
The Public address of account owning assets
Example:
ownerAssets(0xaabb)
Get assets purchased by an account¶
This function retrieves the list of assets purchased by an account. Parameters:
account
The Public address of account that purchased the assets
Example:
consumerAssets(0xaabb)
Get the computation logs of a workflow execution¶
When a user triggers a compute execution via the execute
function, this execution is scheduled and de-attached of the api method triggering it.
This function returns the logs generated during the execution of the multiple stages of a workflow in the data publisher infrastructure.
This function requires the executionId
and agreementId
for getting the logs. Parameters:
agreementId
Identifier of the service agreement between the consumer and the publisherexecutionId
Identifier of the execution related with the agreement executedaccount
The Public address of account used to execute the computation
Example:
computeLogs("8974328", "ababacc", 0xaabb)
compute status¶
When a user triggers a compute execution via the execute
function, this execution is scheduled and de-attached of the api method triggering it.
This function returns status of the jobs executed in the data publisher infrastructure.
This function requires the executionId
and agreementId
for getting the logs. Parameters:
agreementId
Identifier of the service agreement between the consumer and the publisherexecutionId
Identifier of the execution related with the agreement executedaccount
The Public address of account used to execute the computation
Example:
computeStatus("8974328", "ababacc", 0xaabb)
Non-Fungible Tokens (NFTs) associated to assets¶
A Decentralized Identifier (DID) that digitally represents some physical stuff, aligns quite well with the concept of a Non-Fungible Token (NFT). The implication is that, if you are an asset owner in Nevermined, you can mint NFTs associated with your DID and distribute them amongst your customers or users.
Mint a NFT associated to an asset¶
This function allows to a DID owner to mint NFTs associated to the DID. Parameters:
did
Identifier of the asset where the NFTs will be mintedamount
the amount of NFTs to mint associated to the DID
Example:
mint("did:nv:1234", 5)
Burn NFTs associated to an asset¶
This function allows to burn existing NFTs associated to a DID. Parameters:
did
Identifier of the asset where the NFTs will be burnedamount
the amount of NFTs to burn associated to the DID
Example:
burn("did:nv:1234", 1)
Transfer NFTs associated to an asset¶
This function allows to transfer NFTs associated to a DID between accounts. Parameters:
did
Identifier of the asset where the NFTs will be burnedaccount
Public address of the account where the NFTs will be transferredamount
the amount of NFTs to burn associated to the DID
Example:
transfer("did:nv:1234", 0xabab, 2)
Get NFTs balance associated to an asset¶
This function allows to get the NFTs balance of an account for a DID. Parameters:
account
Public address of the accountdid
Identifier of the asset with NFTs associated
Example:
balance(0xabab, "did:nv:1234")