https://github.com/morpho-org/morpho-data-structures

Data structures tested and used by the Morpho Protocol.
https://github.com/morpho-org/morpho-data-structures

data-structures doubly-linked-list heap solidity

Last synced: about 2 months ago
JSON representation

Data structures tested and used by the Morpho Protocol.

• Host: GitHub
• URL: https://github.com/morpho-org/morpho-data-structures
• Owner: morpho-org
• License: agpl-3.0
• Created: 2021-10-03T09:19:55.000Z (over 3 years ago)
• Default Branch: main
• Last Pushed: 2024-12-22T21:27:59.000Z (5 months ago)
• Last Synced: 2025-03-29T13:04:45.986Z (about 2 months ago)
• Topics: data-structures, doubly-linked-list, heap, solidity
• Language: Solidity
• Homepage:
• Size: 3.48 MB
• Stars: 115
• Watchers: 10
• Forks: 13
• Open Issues: 3
• Metadata Files:
  • Readme: README.md
  • License: LICENSE
  • Audit: audits/Morpho_Omniscia.pdf

Awesome Lists containing this project

README

        
# Morpho Data Structures 🦋

This repository contains the data structures that are used in Morpho Optimizer's matching engine.

The data structures are built to be secure and gas efficient.

## Double Linked List

The current implementation of the double-linked list is based on this [article](https://hackernoon.com/a-linked-list-implementation-for-ethereum-deep-dive-oy9432pa) written by Alberto Cuesta Cañada. You can find the repository [here](https://github.com/HQ20/contracts/tree/master/contracts/lists). Note that the code has been modified to meet our own needs and to allow us to sort the first accounts of the double-linked list. Our implementation is not a generalized one.

What you can do with it:

- Insert an address sorted by a value passed along this address.

- Insert (and its value) before an account.

## Red Black Binary Tree

A [Red Black Binary Tree](https://en.wikipedia.org/wiki/Red%E2%80%93black_tree) is a kind of binary tree that allows insertion/deletion/search in `O(log(n))`.

Our implementation is a modified version of the [OrderStatisticsTree repository](https://github.com/rob-Hitchens/OrderStatisticsTree) written by [Rob Hitechn](https://github.com/rob-Hitchens) which is also based on [BokkyPooBahsRedBlackTreeLibrary repository](https://github.com/bokkypoobah/BokkyPooBahsRedBlackTreeLibrary) written by [bokkypoobah](https://github.com/bokkypoobah).

Our modified version makes keys unique items instead of just (key, value) unique pairs.

In order to manipulate a binary tree and visualize how it manages to stay balanced, this [tool](https://www.cs.usfca.edu/~galles/visualization/RedBlack.html) is very useful. You can also find [here](http://ion.uwinnipeg.ca/~ychen2/advancedAD/Red-black%20Tree.pdf) the pseudo-code logic of the tree's function.

## Heap based ordering

This implementation is based on a heap data structure and refines it by adding an unsorted portion after it. This gives us an approximation of a heap, and thus operations are performed in constant time.

At least the first `maxSortedUsers / 2` addresses are sorted in the Heap. To keep constant time operation, we divide by two the size of the Heap once the size overtakes the `maxSortedUsers` number. It means that we remove all leaves of the heap.

The choice of this implementation is explained by the desire to store a maximum of high-value nodes in the heap to use them for peer-to-peer matching.

Indeed, a naive implementation that would remove the tail and insert new values at `maxSortedUsers` (once the heap is full), would end up concentrating all new values on the same single path from the leaf to the root node because the `shiftUp` function will be always called from the same node. The risk is that low-value nodes stay in the Heap and that all the liquidity will be concentrated on the path from the leaf of index 'maxSortedUsers' to the root.

Removing all the leaves enables the protocol to remove low-value nodes and to call the `shiftUp` function at different locations in the Heap. This process is meant to keep a maximum of liquidity available in the heap for peer-to-peer lending.

The main entry point is the `update` function, calling internally either `insert`, `increase`, `decrease` or `remove`.

## Other data structures

Other data structures may be explored in the future and we are open to any suggestions or optimization of current implementations ⚡️

# Audits

The code concerning the [heap based ordering data-structure](./contracts/HeapOrdering.sol) has been audited by [Omniscia](https://omniscia.io) and the report can be found [online](https://omniscia.io/reports/morpho-heap-ordering-structure/) or in the file [Morpho_Omniscia](./audits/Morpho_Omniscia.pdf).

# Licenses 

The data structures are licensed under `AGPL-3.0-only`, see [LICENSE](./LICENSE).