DeviceID

Address: 0x22Dc95682aB184d6051430f0e6afe587a64E6851

Whitelisted attributes: IMEI, hardware serial #

Overview

In summary, the DIMO registry contract is used to onboard IoT devices onto the protocol during manufacturing by creating a device through a smart contract. The smart contract tracks the identity of the device throughout its lifecycle and binding process is used to associate the device with its owner's blockchain wallet address. The identity of the device is a SECP256K1 ethereum address, which allows the device to transact on its own like any other EOA wallet on the ledger. This allows for ownership transfer and management of multiple devices by a single owner.

Attributes

DeviceID's contain on chain customizable attributes which can be set during creation time and some can be updated by the manufacturer after the fact. By default, manufacturer can specify:

• 0x Address

• Serial Number

• Hardware Revision

• IMEI

Additional attributes can be whitelisted by the foundation.

Manufacturer Onboarding

When onboarding IoT devices, each device gets created in the DIMO registry contract to onboard into into the protocol.

Creation

To create a device, a manufacturer asks the secure element of the device to provision a key. That public key is then passed through a smart contract to mint the device.

Lifecycle

The smart contract then tracks the identity of the device through it's lifecycle. This handles cases of provisioning, claiming, factory resets, OTA and end of life.

Claiming

When received by the user, device goes through a "binding" process. The purpose of device binding is to associate a device with its owner’s blockchain wallet address.

Typically, multiple devices can be associated with the same owner, who will then be able to manage every single device, benefit from any value generated by the devices, and even transfer the ownership to another account.

User Association

Typically, multiple devices can be associated with the same owner, who will then be able to manage every single device, benefit from any value generated by the devices, and even transfer the ownership to another account.

This contract represents an aftermarket device owned by a DIMO user or a manufacturer. The same way, an aftermarket device must be minted under a Manufacturer node.

Technical Details

Minting

Although aftermarket devices are made to be connected to vehicles, they might live in the DIMO system without an initial vehicle node relationship. In order to be able to call the function mintAftermarketDeviceByManufacturerBatch to mint devices, a manufacturer must have the following:

• Hold the role MANUFACTURER_ROLE

• Have a valid License, that is validated by the AdLicenseValidator contract

• Be the owner of the node the will be the parent of the devices minted

• Have enough DIMO tokens to mint all devices requested

Each device to be minted has a cost associated with it that is charged in DIMO tokens. The tokens spent to mint aftermarket devices are transferred back to the Foundation. For instance, if the cost is 50 DIMO and the manufacturer wants to mint 300 devices, in addition to the above conditions, 300*50 = 15,000 DIMO tokens.

Besides the NFT ID, the AftermarketDevice nodes also have a mandatory 0x address associated with them. In order to prevent duplicated nodes, two mappings are employed to verify existing data before minting:

// AD address => AD Id
mapping(address => uint256) deviceAddressToNodeId;
        
// AD Id => AD address
mapping(uint256 => address) nodeIdToDeviceAddress;

Whenever a new AftermarketDevice is about to be created, the new 0x address is verified against the existing ones to ensure it is not associated with an ID. It also facilitates external interfaces to query the 0x addresses and IDs of the nodes.

Claiming

The purchase of a device by a user in the real world is not an easy event to track on-chain. Nevertheless, we rely on a claim procedure to guarantee that the appropriate user possesses the proper device both in the real world and on-chain. Some steps are taken, and users must adhere to them, to ensure data consistency and prevent users from claiming the wrong device. The claimAftermarketDeviceSign function only accepts calls from authorized addresses, and metatransaction is the mechanism employed to allow users to claim their devices with the following steps:

1. The user accesses the DIMO app to request to claim their device.

2. Both the user and the device sign a typed structured message with the following information:

   • Aftermarket Device node: token Id associated to the aftermarket device.

   • Owner: the address of the user.

3. The request is submitted to the server that will perform verifications to ensure the given information matches the user’s data.

4. The server sends a transaction to the AftermarketDevice contract invoking the function claimAftermarketDeviceSign containing the information above along with the bytes of the signatures submitted by the user and by the device.

5. The contract performs the following instructions:

   1. Verifies if the AftermarketDevice node exists.

   2. Verifies if the aftermarket device is not already claimed.

   3. Recreates the user’s and device's messages with the same information passed as arguments.

   4. Utilizes Eip712Checker to recover the signer of both messages.

   5. Verifies if the signers recovered matches the owner candidate of the aftermarket device and the device itself.

   6. Sets the device as "claimed".

   7. Transfers the AftermarketDeviceId to the user.

Keep in mind that before performing the last step above, the manufacturer must approve the DIMORegistry contract.

Pairing

Similarly, it is challenging to ensure the user connects the proper device to the right vehicle. Once again, we rely on a procedure involving metatransactions to write the information on-chain:

1. The user accesses the DIMO app to request to pair their device with their vehicle.

2. The user signs a typed structured message with the following information:

   • Aftermarket Device node: token Id associated to the aftermarket device.

   • Vehicle node: token Id associated to the vehicle.

3. The request is submitted to the server that will perform verifications to ensure the given information matches the user’s data.

4. The server sends a transaction to the AftermarketDevice contract invoking the function pairAftermarketDeviceSign containing the information above along with the bytes of the signature submitted by the user.

5. The contract performs the following instructions with more extensive verifications:

   1. Verifies if both AftermarketDevice and Vehicle nodes exists.

   2. Verifies if the aftermarket device is claimed.

   3. Verifies if the owners of the vehicle and aftermarket device matches.

   4. Verifies if both vehicle and aftermarket device are not already paired.

   5. Recreates the user’s message with the same information passed as arguments.

   6. Utilizes Eip712Checker to recover the signer of the message.

   7. Verifies if the signer recovered matches the owner of the vehicle and, consequently, the aftermarket device.

   8. Pairs the vehicle and the aftermarket device.

Once a user claims ownership of an aftermarket device and pairs it with their vehicle, a second link is established between the device and the vehicle in which it is installed.

Please note that the Mapper module is used to create the connection between the Vehicle and the AftermarketDevice.

Unpairing

Ideally, the aftermarket device would always be paired with the same vehicle. However, in the real world, a user can sell their vehicle, give it to someone else, or even damage the device. This means that we have to enable the user to unpair their device if needed. The procedure once again employs a metatransaction and is quite similar to the pairing process:

1. The user accesses the DIMO app to request to pair their device with their vehicle.

2. The user signs a typed structured message with the following information:

   • Aftermarket Device node: token Id associated to the aftermarket device.

   • Vehicle node: token Id associated to the vehicle.

3. The request is submitted to the server that will perform verifications to ensure the given information matches the user’s data.

4. The server sends a transaction to the AftermarketDevice contract invoking the function unpairAftermarketDeviceSign containing the information above along with the bytes of the signature submitted by the user.

5. The contract performs the following instructions with more extensive verifications:

   1. Verifies if both AftermarketDevice and Vehicle nodes exists.

   2. Verifies if the aftermarket device is claimed.

   3. Verifies if the owners of the vehicle and aftermarket device matches.

   4. Verifies if both vehicle and aftermarket device are paired with each other.

   5. Recreates the user’s message with the same information passed as arguments.

   6. Utilizes Eip712Checker to recover the signer of the message.

   7. Verifies if the signer recovered matches the owner of the vehicle and, consequently, the aftermarket device.

   8. Unpairs the vehicle and the aftermarket device.