Aegora/Vanillae post series

We are finally getting around to writing our series of posts explaining Vanilla, the marketplace project that is based on it, and a few other pieces that cover the mechanics of chains in general and Aeternity in particular.

The post that covers the rationale for Aegora can be found here:

Interesting article, thanks for sharing this :slight_smile:

" the fastest solution is to get 0.1AE from someone (we’ll even help if you have something you want to sell — send me an email) and sell something on Aegora."

Wouldn’t it be easier to have a solution with generalized accounts for this? :thinking:

Also I’m curious about this one:

“Our approach so far has been to implement a system of live price adjustments between buyer and seller, and the buyer’s ability to put a block on a trade pending an agreed price adjustment.”

Do you mind going more in-depth into how you solved this problem on a technical level?

1 Like

That should be possible, but invites a lot of complexity that we would much rather handle through a non-automated solution, such as direct spends signed by a human we can talk to. GAs have tremendous utility but also bring along the potential for someone to, say, spawn a ton of wallets and spam what would essentially be a GA faucet to nab “starter funds” from us with zero verification, and this could easily be automated.

Currently we like the idea of:

  1. Someone having to take the time to send us an email.
  2. One of us having to take the time to have a short conversation with the person and go through the process of signing a spend to them.
  3. Backstopping this process by the inherent human bandwidth limitation represented by 1 and 2 above.
  4. This problem should be temporary – friends who sell something on Aegora should be sending their own friends 0.1AE or people should be buying their own AE on an exchange, as ultimately the distribution of AE must expand across ordinary people who want to buy and sell things rather than be dependent on just Tsuriai being able to fund the entire world in 0.1AE increments.


When a buyer clicks “BUY” on an item on the site a contract call is created that will commit the amount of the sale into the contract. Note, this money does not yet go to the seller, but rather it is held by the contract until final two-way acceptance of the sale.

At this point the sale item is no longer visible on the sale browser and is instead found in the “in progress sales” or “in progress buys” part of the seller and buyer’s user navigation, and the sale item page itself becomes a message log between the two. The buyer can (and in most cases should) place a “block” on finalizing the transaction which prevents the seller from claiming the funds until the block is removed.

During this period the buyer can message the seller, and the seller the buyer – and the seller can update the price up or down. If the price is adjusted down the buyer is refunded the difference at that moment, and if the price is adjusted up the sale cannot be completed until the buyer commits the difference to the contract (there is a button for this).

Most sellers will require a price adjustment no matter what, because they will need to negotiate shipping overhead. Occasionally the buyer may want to renegotiate the price, however, simply due to the volatility inherent in crypto prices.

Once both parties have agreed to the final price, the full price has been paid into the contract by the buyer and the buyer has removed any block on the sale, the seller can then click “accept” and receive the funds – at which point the sale item page (which is still for now a log of all messages between buyer and seller as well as a log of all on-chain transactions adjusting prices, blocks, etc. to date) changes to add an item-reception section where the buyer can review the seller and register whether or not he received he desired item.

Either party can reject involvement in the sale at any point prior to acceptance of the sale, at which point the buyer is fully refunded and the contract goes back into “NEGO” status and is once again made visible on the sale browsing screens of the site.

All of the price adjustment, sale blocks, acceptance, rejection, etc. are governed by contract calls on-chain and the statuses of those calls are verified by the site backend (listed as “pending changes” until they are confirmed on-chain).

1 Like

Here we are with the explainer post I mentioned to @erik.chain above.

I did plagiarize myself in the “how does a sale work?” section, but here is the whole thing:

Further posts will be coming along that explain different aspects of Aegora, what we are planning for the future, and especially problems that we encountered writing it and how the Vanillae library and Sidekick projects got us around some of them, as well as discussion about some things we have planned for the future.

The basic idea we are going with here is that Aeternity already has the properties necessary to make it a commerce-coin (which most crypto actually lacks, sadly) and we are interested in leveraging that to encourage real work in the real world of atoms.


Thanks for sharing @zxq9
looking forward to reading about how you mastered those challenges :slight_smile:


Thanks! The intention is to follow up with a few posts about the journey itself, what we found hard, gaps we identified, how we solved them and by the end basically spell out how anyone else could emulate what we’ve done using the tools we used (new libraries like Vanillae and Sidekick along with suggestions for alternatives), as well as ways the Aeternity nodes themselves are evolving in ways to make this kind of commercial use case easier to manage based on these experiences.

That’s a lot of ground to cover. Hopefully I don’t put everyone to sleep too fast.


Continuing the journey, this time with a low-level post about RLP, thanks this time to efforts from @pharpend.

This post is a low-level explainer about what RLP is, how it works, with examples crossing Erlang, Typescript and referencing the Ethereum project’s Python implementation.

These low level posts provide the reference material necessary for writing some of the higher-level ones that will follow.


And another low-level explainer, this time base64 VS base58, which turn out to be entirely different algorithms, not just the general “encode X in base-N”, despite the names seeming to indicate that.


I believe that Aegora has significant potential for growth and success. After watching the video: CRYPTO? OMG! Buy REAL THINGS with CRYPTO NOW?!? - YouTube I would like to add a couple of suggestions and questions, from a user experience perspective.

  1. In the header or somewhere on the side there can be some sections called “About”, “How Aegora works” or “Why Aegora” with a clear and concise explanation of how the platform works. This can help people to understand more what is the idea behind the project. There can also be an F&Q part.

  2. Reviews and ratings for sellers to help build trust and confidence among buyers. This feature could include a rating system based on the quality of the descriptions provided for the product, was the provided information valid, etc…

  3. Messaging system that allows buyers and sellers to communicate in real time, with the ability to attach files and images. This can be tricky because they can go off-platform, but communication is important, especially for used products, there are random questions for the seller before payment. Comment section bellow the product maybe would be better.

I am excited to follow the development of the project and to help from the user experience/interface point of view. :slightly_smiling_face: :hammer_and_wrench:


Thank you for taking a look!

  1. On-site documentation: Yes, this is planned, but we still are trying to figure out the best way to convey in a simple way such a complex subject. In particular the trouble of explaining Aegora to someone who already understands blockchain is a totally different proposition than explaining it to someone who has no idea what a blockchain is. This is harder than expected, hence the current documentation effort as a sort of general mapping exercise to get us to the point to where we can actually roadmap a solution to the explanation problem.
  2. Review system: A review system is in place that allows users to view a seller’s history and general rating, including the total volume by AE (as opposed to just sales incidents) that have passed through a seller (to prevent the problem of people faking it by selling to themselves 1000 times with sales of 0.1 AE or similar). The current system is imperfect, but your idea about user ratings for sellers being the only way to instill confidence in a given seller is exactly the same idea we’ve had ourselves. Trust online is a major problem and ratings + past performance seems the only way to approach it.
  3. Buyer <-> Seller messaging: Each sale item becomes a message log between buyer and seller whenever a buyer commits to a purchase. What is communicated between the buyer and seller here is completely up to them (and is visible only to them) – we aren’t doing that silly thing where we try to block the posting of email or social media addresses or whatever, if they want to engage in a rich chat interface they absolutely can. After the sale is concluded (after the buyer has closed the issue and reviewed the seller) the message log between buyer and seller is deleted and only the review remains in data archive.

The issue of images turns out to be more complex legally than we had expected, due to the trouble of regulators demanding internal access in the event of “illegal image” sharing. This problem is, of course, fraught with insane jurisdictional problems (we are based in Japan where this is less of a legal concern, but that doesn’t mean the US or European governments won’t try to apply legal pressure and squash us dead with international legal fees and bans) – so our decision at the moment, while we lack the resources to contend with such problems, is to simply limit images to whatever we can review ourselves in the initial moderation step.

The biggest and most glaring usability issue is definitely item 1 above, which is why we are focusing on the broader documentation effort right now to pave the way for a really good on-site documentation section (and there is no way to escape providing multiple formats: text, images, videos, etc. explaining all this). Hopefully we can get through this phase quickly! It all boils down to how many hours we can commit to it, really.


The saga continues…

We’ve been held up with a few issues the last two weeks. One is trying to decide which order to put drafts in and what constitutes an “entry in the series” vs what should be a sub-section of a given post. The other has been managing packaging issues that were surprisingly finicky (vanillae has a relatively large number of deps that had to be packaged), but should be all resolved as of COB today.

The TL;DR is that the vanillae.erl lib will be packaged and available via ZX, and a (really simple) GUI demo app that shows you how to actually use it from within an Erlang project will be available so you can get a firsthand example of how to use the thing by running zx run aedemo (zx protip for development: if you do zxh run aedemo you can play with all the primitives from a live repl, which is nice).

We’ll probably make a video explaining how to make use of all this soonish.


I read your posts, introductions, and websites in their entirety and it was very interesting. Is it open source?


Yes, the Vanillae library is open source. We are aiming for a v1.0 release of it next week. There are a few features implemented in Vanillae right now that really should be a part of the node, and I am in the process of refactoring the HTTP endpoints to the node to accommodate these features at the moment so we can move some of the complex code in Vanillae into the node (this will make it possible to create a Vanillae library for other languages much more easily).


When I say Aegora, I’m interested in how it works as a whole. I want to see how its smart contracts are implemented.

1 Like

OK! I have a presentation I’m working on about the Aegora architecture that I’ll post a link to here when I am finished recording it (it will be a video with an accompanying blog post).

The smart contracts themselves are here: GitHub - zxq9/contraects: Sophia contracts for Maerket
If you watch the YouTube video ( CRYPTO? OMG! Buy REAL THINGS with CRYPTO NOW?!? - YouTube) it will be easy to follow how each action on the site maps to a function in the base contract (at the time of posting a sale to the chain initially) or in the sales contract (almost everything else).

There are two contracts, the “base contract” and the “sales contract”.
The base contract acts as a lookup base for finding sales contracts, because each sales contract is actually cloned from a template (this dramatically reduces the size of each sales contract on chain). The important logic about how each sale is actually handled (how each sale passes through the states that govern what action is permitted to be taken when) is all in the sales contract.

This two-layer structure gives us the ability to add additional types or updated versions of template sales contracts in the future, and the code inside aegora itself permits us to create new generations of base+sales contracts as design requirements change (by remembering which version was the deployment target up to a certain given ID). This structure also allows us to rebuild the state of all current contracts just from on-chain data, refund everyone all at once, and re-start our service in the ultimate disaster case (if the Tsuriai servers all disappear in a gigantic earthquake, for example) as long as we have a record of the base contract’s address somewhere.

As an example of future design requirements changing, Tsuriai is planning on creating at least three additional versions of sales in the future:

  1. Managed escrow (third-party signature required for claiming funds)
  2. Shipping company integration (in this case the shipping company’s delivery becomes a third-party escrow signature, essentially)
  3. Auction-style sales

Each of these would have very different logic, of course, and that logic must be understood by the Aegora website backend to be able to provide interfaces to these things, but the on-chain logic of the base contract does not have to change too much to be able to provide the indexing and emergency funds-rescue functionality.


Thank you very much for your introduction, which makes me have a deeper understanding.
I fork a copy and am reading it.

1 Like