Introducing the Aergo Connect API, a lightweight method to enable websites to communicate with the Aergo Connect browser extension in a secure and privacy-preserving way.
Introduction
Aergo Connect is currently the only officially supported graphical wallet to manage Aergo native accounts. It supports the core use cases for token holders, but can’t do much else.
Even though Aergo’s long term UX vision is that wallets are not necessary for dapp end users, or at least don’t require additional software installation, for now we need a simple way to enable developers to build and test web apps, both official and third-party. Many users are already familiar with Metamask-style request popups, so that’s what we’re going to offer.
API features
Through the API, websites can send permission requests to Aergo Connect. After user confirmation, the result is sent back to the website. Currently, the following four basic messages are supported:
- Get account address
- Sign message
- Sign transaction
- Send transaction
You can find the complete documentation here: https://github.com/aergoio/wallet-extension/blob/master/API.md
Privacy, security, and usability considerations
Opening up software with an API needs careful consideration for security and privacy. Over the years we have been following developments in the Ethereum community and have applied the many learnings.
Regarding privacy, it is important to not leak any information without explicit user consent. Early Metamask versions injected information into every website you visited, which enabled fingerprinting and targeted phishing attempts. Aergo Connect uses a protocol that only gives information to websites after explicit user interactions. We learned a lot from the related discussions regarding EIP1102.
The API opens the extension up to any website, so there needs to be a safe way of linking the two sides. We achieve a decoupled connection between website and extension by using browser-native messages and events. A very light-weight content script is injected into every page which does nothing but receive messages and relay them to the extension. Upon completion of a request, an event is passed back to the website. This ensures that a website can never gain direct access to data stored in Aergo Connect.
When a dapp requests users to sign a transaction, it is important to be able to understand what exactly you are signing. That’s a big advantage of the Aergo platform. On Ethereum, contract call data in transactions uses a packed encoding scheme that is not human readable. This has lead to EIPs such as “typed structured data hashing and signing”. On the other hand, on Aergo, this data is expressed as JSON objects, which are much more user friendly and can be displayed in a human-readable form in a wallet. We encourage developers to provide call data using the field payload_json so that it can be displayed in Aergo Connect well.
What this API does not do
Unlike Metamask, we decided to not inject full-featured node providers and Herajs clients for a number of reasons.
Metamask itself has started removing this automatic API injection in favor of giving power and extensible tools to dapp developers. Injecting features may sound useful in the beginning, but actually it creates friction and technical dept as APIs change and you need to keep all parts up-to-date. That’s why this API aims to just provide the bare basics: a protocol for exchanging messages to request user permissions.
Metamask apps often use Infura as a default blockchain RPC provider, but really this should be a conscious decision by the developers (and users), not something that’s managed by a wallet. Aergo provides its own Infura-like service (a public GRPC API at mainnet-api.aergo.io), but developers need to be aware of the limitations. Enterprises may want to run their own fullnodes for API access.
As outlined in our previous article, we envision end-user products built on Aergo to self-manage wallets and nodes and not rely on external software to be installed by users. Aergo offers SDKs that have wallet capabilities (Javascript, Java), so it’s easy to do key management yourself. It can be coupled with hardware wallets (e.g. Samsung Keystore) or layer-2 identity solutions such as Burner Wallets or Identity/proxy contracts (which we at Aergo are also researching at the moment).
We want to encourage dapp builders to consider these aspects and make apps work standalone without relying on additional software. But if you need something that works now, perhaps for a quick demo or an app targeted at advanced users who have a good understanding of blockchain technology, the Aergo Connect API is a good choice.
Conclusion
With the Aergo Connect API, we offer a simple way to request permissions from the user through Aergo Connect in a secure and privacy-preserving way.
You can see it live in action on Aergo’s new Voting Page: https://voting.aego.io
Install Aergo Connect to manage your stake and votes in that application. We also have a full step-by-step guide on how to use it.