DIMO Connection Oracle example repository
Recommended reading: DIMO Developer docs.
An application that exposes an API and performs data streaming from your data source to a DIMO Node. The API is used for a frontend to handle onboarding and removal. The data streaming pulls data however you need it to from your systems and then forwards it via an http POST to a DIMO Node. This app also does minting of necessary on-chain records. This repository is an example in Golang of a DIMO Oracle, which you can base your solution on and just replace necessary parts.
This is an on-chain object that basically represents your Oracle on-chain. It is required to be able to send data to a DIMO Node and run an Oracle.
This represents the vehicle on-chain. It stores basic information such as the owner wallet address as well as the Make Model Year. You can query for them using our Identity-API - docs
When you onboard a vehicle, the oracle will mint a vehicle NFT as part of the process. The two key inputs are the definition_id and the owner 0x address.
This represents the software connection between the Vehicle NFT and the Connection, eg. your oracle. When the connection is removed, this should be burned. docs Every payload is signed by the Synthetic Device. We have examples of this in the repository.
An easy way to handle for DIMO users to login with DIMO via an auth redirect flow. You will likely need to implement this to handle the login for the vehicle onboarding. If you're doing Fleet onboarding, where a single user or few users manage many vehicles, your UI should reflect that. If you're building for retail/consumer users, you'll want onboarding to be centered around a single or few vehicles with explicit ownership verification mechanisms, eg. maybe you do an OAuth flow with your system or require the user to input something specific to that vehicle or PIN code etc.
- Register an account on https://console.dimo.org/
- Generate an API key and add your preferred redirect URI
- Create your Connection License. In the future this will be in the dev console but for now provide your ClientID to your developer relations person at DIMO.
- Obtain the required Synthetic Device Minting roles - engineers at DIMO will do this for you.
- Create an Account Abstracted wallet with zerodev, we'll call this the Developer AA Wallet - engineers at DIMO can do this for you.
- Fund your Developer AA Wallet with some DCX. You can do this from the DIMO Dev Console. Required for the minting operations.
If you look at the go package internal/onboarding you'll see an example we've built for this.
In general, onboarding in this example codebase happens through a couple API endpoints, and then all the operations are handled
by a backend job (we use river for the jobs). Jobs are stored in the database.
THe REST endpoints that handle onboarding are in internal/app/app.go. The process of onboarding boils down to:
- Decoding the vehicle's VIN or whatever identifier is used. The example code uses DIMO Protocol decoder. If your VINs are uncommon to decode, please reach out.
- Enrolling the vehicle with your backend, whatever way makes sense to you. Basically it tells your external system it's ok for this Oracle app to connect to it.
- Minting the Vehicle NFT. This creates the on-chain representation of the vehicle, with the owner set to your logged in wallet 0x.
- Minting the Synthetic Device NFT. This represents the connection of the Vehicle NFT to your software connection. Contains your oracle's connection license 0x.
- Optionally Sharing & setting Permissions via DIMO SACD. If you know you'll be sharing vehicles you onboard immediately with a customer for example, you can include SACD permissions.
Minting operations above require your Developer AA Wallet address to have DCX balance to pay for the operations.
This implements the onboarding process with your external system. It has a common interface with 2 functions:
- Validate: used to check if the VIN (or identifier) is compatible with your system. You could imagine this calling out to some endpoint in your system that checks.
- Connect: actually onboards the VIN (or identifier) into your system so that it knows to allow connections however you with to implement it - Streaming, grpc, kafka, REST etc.
There is an example struct implementation ExternalOnboardingService in this file, but feel free to change it up as needed.