[Active] Application: Vanillae

(Note: had to convert hyperlinks to monospace text because the forum won’t let new users post things with too many hyperlinks. Sorry)

Application Status

  • Status: Approved on the 01.07.2022, submitted on the 09.05.2022
  • Last updated: 09.05.2021 (May 9, 2022)
  • Submitted by: Peter Harpending
  • Team:
  • Approved Budget (in h):
  • Used Budget (in h):
  • Planned Delivery: Q1 2023

Specify the funding category

Open Source Development

Application Title




Value Application

The backbone of the economy is everyday small business transactions: things like groceries, gas, and coffee. Look at your last bank statement. What percentage of your transaction volume is transactions over $1000? Mainstream cryptocoins are largely useless in the space of transactions less than $1000 due to their transaction bottlenecks. Nobody wants to wait 45 minutes (or 28 hours) for coffee.

Aeternity is in the unique position of being good enough on a technical level to handle the “grocery store” category of transactions. Aeternity even can beat Visa in some cases, amazingly. Visa isn’t performant enough to run the Tokyo subway pass system. Aeternity is. The barriers to grocery-store adoption are mostly tooling-related, both in the space of developer-facing tooling and user-facing tooling.

Broadly speaking, Craig and I would like to improve the space of tooling. Our initial goal is to provide a thoroughly beaten path for the e-commerce world to begin adopting contract-based Aeternity payments. E-commerce already relies on electronic payment systems. These generally incur a very high audit and compliance overhead. Aeternity has the potential to be an easy-to-use lightweight alternative where most of the security and accounting overhead is automatically offloaded to the blockchain.

Right now, if you want to accept electronic payment, it is harder to use Aeternity than to use Stripe. We want Aeternity to not just be easier to use, but to be the obvious choice.

Definition of Terms

General description of Vanillae

“We” means myself and Craig Everett. “You” means a hypothetical commercial user or commercial developer.

Our current heuristic is to build out a simple tool suite in Erlang and TypeScript implementing the minimal necessary functionality for our commercial application (simple smart contracts based e-commerce store).

The initial assumptions are:

  • Your server backend will be written in Erlang (or another BEAM language)
  • You are serving your application over HTTP
  • Your customers interact with your application via a web browser
  • Your customers pay using a browser wallet extension

We also would like Vanillae to be a reference implementation for people who want to write Aeternity APIs for other languages or protocols. For instance, at some point, there will need to be Aeternity APIs in Dart and Swift. There will also need to exist support for native binary protocols for bandwidth constrained environments where HTTPS is not appropriate.

General methodology of Vanillae

  1. “I need to do X”
  2. “What is the processing pipeline for X?”
  3. Implement that processing pipeline from back to front


  1. Generate a keypair
  2. Compile a contract
  3. Deploy a contract
  4. Call a contract
  5. Spend
  6. Query the chain with dry-runs
  7. Clone a contract

Components of Vanillae

  1. JR: Jaeck Russell (self-contained browser wallet)
  2. SK: Sidekick (self-contained in-page wallet connector)
  3. EAPI: Erlang API (backend serializers)
  4. EJAA: Erlang JavaScript “API” API (connectors for AE networks)


Improve the adoption path for commercial users who want to integrate Aeternity into ordinary business applications.

We want to make the entire pipeline of development as frictionless and painless as possible. We want Aeternity to be the obvious and easiest-to-use payment backend for both hobbyist and commercial applications.

We want small businesses to have this conversation internally:

  • Boss: “What are we going to use as our payment backend?”
  • Developer: “Let’s use Aeternity. Aeternity is easy to use”

Status Quo

The SDK is currently optimized for esoteric crypto applications implemented entirely in the Node/NPM ecosystem. There is currently no tooling optimized for vanilla e-commerce applications implemented in the BEAM ecosystem.

Vanillae is not a fully-featured replacement for the current JavaScript SDK. Our scope is quite different. Vanillae will be optimized for vanilla e-commerce applications written in the Erlang ecosystem. For instance, nothing in Vanillae will cover the domain of server-side JavaScript, nor will Vanillae cover the more esoteric features of Aeternity (e.g. AENS, AEX-9, NFTs, derivative coins, etc.).

Required Work

Roadmap for v0.1:

Accepting that the first casualty of any battle is always the plan, our tentative plan is to follow this roadmap.

  1. Discovery

    1. (16 hr) Prototype in docs and typedefs the EJAA.
    2. (16 hr) Prototype in docs and typedefs the EAPI.
    3. (16 hr) Convert the existing Sidekick project to be doc-tool friendly and expand error handling and live debug facilities.
    4. (80 hr) Create a prototype browser wallet plugin with as minimal a feature set as possible and as few dependencies as possible.

    Total: 128 hr

  2. First iteration goal: generate, sign, post and query spend TX.

    1. (80 hr) Implement minimum query and TX post functionality in EJAA.
    2. (80 hr) Implement minimum serialization functionality necessary in EAPI.
    3. (40 hr) Modify Sidekick to whatever degree necessary to achieve the iteration goal talking both to Superhero and Jaeck Russell.
    4. (80 hr) Implement minimum necessary signature, keyhandling and user-communication functionality in Jaeck Russell.

    Total: 280 hr

  3. Second iteration goal: generate arbitrary contract post, call and dryrun.

    1. (32 hr) Implement dryrun query functionality in EJAA.
    2. (40 hr) Expand serialization functionality in EAPI if necessary.
    3. (16 hr) Modify Sidekick to whatever degree necessary to achieve the iteration goal talking both to Superhero and Jaeck Russell.
    4. (80 hr) Add contract call decoding and user-display functionality to Jaeck Russell.
    5. (NA) Establish a uniform and documented practice for ecommerce sites to communicate and reference their Sophia contract sources to customers.

    Total: 168 hr

  4. Third iteration goal: identify functionality gaps and complete documentation

    Total: 80 hr

  • Naive Total: 656 hours
  • Fudge Factor: 2
  • Total: 1312 hours


Roughly 8 months (current hours estimate comes to 1312 hours).

Known Limitations

No known limitations.


We plan to create extensive documentation and video tutorials. We have a commercial project (Maerket) where we will use Vanillae ourselves. We therefore have a commercial interest in making Vanillae useful and attractive to other developers, and an interest in making Maerket a showcase for how to use it in practice.


Everything will be open source with easily accessible code with no proprietary licenses.

We haven’t started work on EJAA, EAPI or Jaeck Russell yet, so they do not have repositories. We currently have repositories for AEL and sidekick:

  • AEL repository: https://github.com/aeternity/launcher
  • sidekick repository: https://gitlab.com/DoctorAjayKumar/sidekick


Our intent is to use this code in commercial projects, and maintain the code for the foreseeable future.

We additionally intend to use these projects as the basis for tutorials and educational materials for the Aeternity ecosystem.


Dear Peter, thank you very much for your application. Vanillae Application is approved by ACF.


Progress report October 5, 2022

Repository: https://github.com/aeternity/Vanillae

Regarding the roadmap

  1. Discovery

    1. EJAA prototype: Done
    2. EAPI prototype: Done
    3. Sidekick rewrite: Done
    4. JR prototype: Partial

    Notes: EJAA and EAPI turned out to be more natural to consolidate into a single API which is now called vanillae.erl. vanillae.erl has yet to be packaged properly for rebar3 and zx. Sidekick had to be rewritten in order to handle logging and multiple sources of errors in a sane way. Jaeck Russell has turned out to be two problems:

    1. How do we write a wallet?
    2. How do we write a browser extension with minimal dependencies?

    We figured out problem #1. We are still exploring problem #2 in the context of our security and tooling constraints.

    Sidekick, Sidekick's examples, and Jaeck Russell naturally share a bit of code in common. In particular, they share type definitions (this is AWCP = Aepp-Waellet Communication Protocol). In order to facilitate this code sharing without depending on insecure packaging tools, we had to write our own packaging tool, which is jex. Originally this was a Python script. As the requirements for jex grew more complex, the Python script became unwieldy and it was rewritten in Erlang. It has also become clear that the building and dependency management process for a browser extension (Jaeck Russell) is significantly more complex than for a library (Sidekick). Therefore, jex must be able to handle the nontrivial build constraints imposed by the extension context.

  2. First iteration goal

    1. Query/TX post functionality: Done
    2. Serialization functionality: Done
    3. Sidekick modification: Pending JR
    4. JR functionality: Pending JR

    Sidekick can talk to Superhero. It cannot talk to JR because JR does not exist yet.

  3. Second iteration goal

    1. Dryrun query functionality: Partial
    2. Expanded serialization functionality: Partial
    3. Sidekick Modification: Pending JR
    4. JR Contract Call Decoding/Display: Pending JR
    5. Establishing Contact Publication Best Practices: Pending
    1. turns out to be a very easy problem to solve, the solution awaits inclusion in JR. Item 2 is partial, pending native Erlang implementation of Keccak.
  4. Third iteration goal

    1. identify functionality gaps: pending real-world commercial use case that is being developed in tandem
    2. completing documention: pending any documentation

When will people in Tokyo be paying for train passes with this? :slight_smile:

The other side of the overall problem is to make it easy for users to use this… including how wallet users would quickly & easily infuse their accounts with whatever AE crypto funds from fiat.