# Assets as Ownable Smart Contracts ## Assets in EW-DOS In the context of EW-DOS, an Asset is a digital representation of a physical or virtual device on the [Energy Web Chain](/energy-web-foundation/ew-dos-technology-components-2023/trust-layer-energy-web-chain.md#the-energy-web-chain). An Asset could represent, for example, a solar photovoltaic panel, a battery, an electric vehicle, or an IOT device. Assets must have a [Decentralized Identifier - DID](/energy-web-foundation/foundational-concepts/self-sovereign-identity-introduction.md#decentralized-identifiers-didshttpswwww3orgtrdid-core) in the Energy Web Chain's [DID Registry](/energy-web-foundation/foundational-concepts/self-sovereign-identity-introduction.md#where-are-dids-persisted) in order to participate in applications and marketplace activities. Once an Asset has a DID, it can take on roles within an organization or application. This is discussed further [below](#asset-enrolment). ### Asset Smart Contracts Assets and their chain of custody are managed by [smart contracts](https://ethereum.org/en/developers/docs/smart-contracts/) that are deployed on the Energy Web Chain. #### [IdentityManager smart contract](https://github.com/energywebfoundation/ew-did-registry/blob/development/packages/proxyIdentity/contracts/IdentityManager.sol) When an Asset is first created, it is registered in the [IdentityManager smart contract](https://github.com/energywebfoundation/ew-did-registry/blob/development/packages/proxyIdentity/contracts/IdentityManager.sol) as an owned identity (the `owner` address being the Asset owner, discussed [below](#asset-owners)). The main purpose of the IdentityManager smart contract is to have a on-chain location which aggregates known assets. In other words, it provides a kind of "asset-registry" functionality. This can allow one for instance, to more easily answer questions such as "how many assets have been registered in total?". While there are many OfferableIdentity smart contracts, there is intended to be fewer IdentityManager smart contracts as the IdentityManager's main purpose is the aggregation of OfferableIdentity information. For instance, an enterprise could have a single IdentityManager to all assets which are registered by their employees. #### [OfferableIdentity smart contract](https://github.com/energywebfoundation/ew-did-registry/blob/3e77c3a5b04254990b2d8f9bf783ec55a3ae8a83/packages/proxyIdentity/contracts/OfferableIdentity.sol) The Asset owner can offer ownership to another DID. The [OfferableIdentity smart contract](https://github.com/energywebfoundation/ew-did-registry/blob/3e77c3a5b04254990b2d8f9bf783ec55a3ae8a83/packages/proxyIdentity/contracts/OfferableIdentity.sol) provides methods to verify, offer and transfer [ownership of Assets](#asset-owners) (these concepts are discussed in further detail [below](#asset-chain-of-custody)). {% hint style="info" %} Other contracts in the Ethereum ecosystem exist which track ownership such as popular NFT contract or contracts which implement [ERC-173](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-173.md) such as [ERC-725](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-725.md). However, a key requirement of Energy Web's asset implementation was that ownership transfers cannot be performed unilaterally and so these aforementioned options were not used. {% endhint %} ### Asset Owners Every Asset must have an owner. Asset owners initiate the registration, transference and enrolment activity of their Assets. This requires them to make transactions on behalf of their Asset, so the owner must have an address on the Energy Web Chain that is connected to an [Ethereum-compatible crypto-currency wallet such as MetaMask](/energy-web-foundation/foundational-concepts/wallets-and-exchanges/software-cryptocurrency-wallets/metamask.md). The owner of an Asset is recorded in the Asset's identity on-chain. ## Asset Chain-of-Custody The [`iam-client-library` Asset service](https://energy-web-foundation-iam-client-lib.readthedocs-hosted.com/api/modules/modules_assets/) provides high-level methods to facilitate the chain of custody for an Asset. Chain-of-custody events ([registration](#register-asset), [ofference](#1-offer-asset) and [transference](#transfer-asset-ownership)) for an Asset are emitted from the [IdentityManager smart contract](https://github.com/energywebfoundation/ew-did-registry/blob/development/packages/proxyIdentity/contracts/IdentityManager.sol). [SSI Hub](broken://pages/-Mdw3RbI2NuPE2daUQdp#ssi-hub) listens for and persists the details of these events. All historical owners of an Asset and the dates of offer, transference and acceptance are accessible through SSI Hub's API. ### Register Asset Registering as Asset involves creating an OfferableIdentity smart contract for the Asset on the Energy Web Chain, and registering its identity in the [IdentityManager smart contract](https://github.com/energywebfoundation/ew-did-registry/blob/development/packages/proxyIdentity/contracts/IdentityManager.sol). This is initiated by the Asset owner. Because each Energy Web Chain address is a valid DID under the `did:ethr` DID method, each asset inherently has a DID. ### Transfer Asset Ownership The owner of a registered Asset can transfer ownership to another address on the Energy Web Chain. (The new owner's address must have signing capabilities in order to [sign transactions](/energy-web-foundation/foundational-concepts/ethereum/transaction-costs.md) associated with asset management). The [OfferableIdentity smart contract](https://github.com/energywebfoundation/ew-did-registry/blob/development/packages/proxyIdentity/contracts/OfferableIdentity.sol) provides methods to facilitate Asset transferance. This contract makes calls to the [IdentityManager smart contract](https://github.com/energywebfoundation/ew-did-registry/blob/development/packages/proxyIdentity/contracts/OfferableIdentity.sol) so that the state of the Asset is updated at each phase of the transfer. #### 1. Offer Asset When a transfer is initialized, an 'offer' of transfer is made to the recipient DID. The state of the Asset identity is marked as 'offered' in the [IdentityManager smart contract](https://github.com/energywebfoundation/ew-did-registry/blob/development/packages/proxyIdentity/contracts/IdentityManager.sol). #### 2a. Accept Asset The DID that the Asset was offered to must accept the Offer before it is transferred to them. [`iam-client-library`](broken://pages/-Mdw3RbI2NuPE2daUQdp#identity-access-and-management-iam-client-library) provides a method to accept the transfer. The Asset's owner is updated in the [IdentityManager smart contract](https://github.com/energywebfoundation/ew-did-registry/blob/development/packages/proxyIdentity/contracts/IdentityManager.sol) to reflect the new ownership. #### 2b. Reject Asset The DID that the Asset was offered to has the option to reject the transfer. The Asset's 'offered' status in the [IdentityManager smart contract](https://github.com/energywebfoundation/ew-did-registry/blob/development/packages/proxyIdentity/contracts/IdentityManager.sol) is set to 'false'. ### Asset Enrolment An Asset can take on [(enrol to) roles within an organization or an application](/energy-web-foundation/ew-dos-technology-components-2023/identity-and-access-management-iam/patterns/governance.md#energy-web-iam-governance-framework). If their enrolment request is approved by the role issuer, the Asset is issued a role-based [verifiable credential](/energy-web-foundation/foundational-concepts/self-sovereign-identity-introduction.md#verifiable-credentialshttpswwww3orgtrvc-data-model). {% hint style="info" %} Read more about role-based credentials in the documentation [here](/energy-web-foundation/ew-dos-technology-components-2023/identity-and-access-management-iam/patterns/governance.md#energy-web-iam-governance-framework) Read more about credentials in the IAM stack [here](/energy-web-foundation/ew-dos-technology-components-2023/identity-and-access-management-iam/patterns/credential-lifecycle.md). {% endhint %} * If the Asset's owner **is an authorized issuer** of the desired role, the Asset owner can directly issue a role-based verifiable credential to their Asset. * If the Asset's owner **is not an authorized issuer** of the desired role, the owner can submit an enrolment request on behalf of their Asset to the issuer. [`iam-client-library`](broken://pages/-Mdw3RbI2NuPE2daUQdp#identity-access-and-management-iam-client-library) provides the high-level methods to request and issue enrolments. See the API documentation [here](https://energy-web-foundation-iam-client-lib.readthedocs-hosted.com/api/classes/modules_claims.ClaimsService). ## Using and Managing Assets in EW-DOS [Switchboard](broken://pages/-MjnrcVU-QLI2E4BbxtZ#switchboard) provides an interface for users to register, transfer and enroll Assets. If you are logged into Switchboard, you can view the Asset management interface [here](https://volta-switchboard.energyweb.org/assets). [`iam-client-library`](broken://pages/-Mdw3RbI2NuPE2daUQdp#identity-access-and-management-iam-client-library) contains the high-level functions for managing (registering, fetching, transferring, etc.) assets and their corresponding data. You can view the service API documentation for Assets in the library [here](https://energy-web-foundation-iam-client-lib.readthedocs-hosted.com/api/classes/modules_assets.AssetsService/). ## Use Case: Stedin Decentralized Asset Management Energy Web and the [distribution system operator](/energy-web-foundation/glossary-of-terms.md#distribution-system-operator-dso) (DSO) [Stedin](https://www.stedingroep.nl/eng) jointly developed a decentralized energy asset management system leveraging the EW-DOS components and architecture [discussed above](#using-and-managing-assets-in-ew-dos). The goal of this collaboration was to: * Facilitate secure, encrypted communication between [distributed energy resources (DERs)](/energy-web-foundation/glossary-of-terms.md#distributed-energy-resources-der) (i.e. solar panels, batteries, etc) and the grid * Enable [DERs](/energy-web-foundation/glossary-of-terms.md#distributed-energy-resources-der) to provide grid services (e.g. selling excess energy back to the grid) Grid assets (e.g, smart meters, distribution automation devices), and [distrubuted energy resources (DERs)](/energy-web-foundation/glossary-of-terms.md#distributed-energy-resources-der) were assigned DIDs. The DID is anchored on the asset's pre-existing SIM cards. Each asset exists as an identity in the [IdentityManager smart contract](#identitymanager-smart-contracthttpsgithubcomenergywebfoundationew-did-registryblobdevelopmentpackagesproxyidentitycontractsidentitymanagersol) on the Energy Web Chain. Cryptographically signed information (such as control signals and commands) from the DSO (Stedin) can then be sent to targeted assets. This allows for an awareness and exchange of grid services between the DSO and DERs. You can read more about this use case in the official press release [here](https://medium.com/energy-web-insights/stedin-the-dutch-distribution-system-operator-announces-partnership-with-energy-web-to-explore-cd278623809b). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://energy-web-foundation.gitbook.io/energy-web-foundation/ew-dos-technology-components-2023/identity-and-access-management-iam/patterns/assets-as-ownable-smart-contracts.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.