{"id":26054847,"url":"https://github.com/morpho-org/morpho-data-structures","last_synced_at":"2025-08-12T02:35:36.717Z","repository":{"id":38328768,"uuid":"413030292","full_name":"morpho-org/morpho-data-structures","owner":"morpho-org","description":"Data structures tested and used by the Morpho Protocol.","archived":false,"fork":false,"pushed_at":"2024-12-22T21:27:59.000Z","size":3645,"stargazers_count":115,"open_issues_count":3,"forks_count":13,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-06-25T02:11:18.277Z","etag":null,"topics":["data-structures","doubly-linked-list","heap","solidity"],"latest_commit_sha":null,"homepage":"","language":"Solidity","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/morpho-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":"audits/Morpho_Omniscia.pdf","citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-10-03T09:19:55.000Z","updated_at":"2024-12-22T21:28:02.000Z","dependencies_parsed_at":"2024-06-19T23:14:25.986Z","dependency_job_id":"dbd96874-e43a-40b6-aafd-3f909dd8172c","html_url":"https://github.com/morpho-org/morpho-data-structures","commit_stats":null,"previous_names":["morpho-dao/morpho-data-structures"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/morpho-org/morpho-data-structures","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/morpho-org%2Fmorpho-data-structures","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/morpho-org%2Fmorpho-data-structures/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/morpho-org%2Fmorpho-data-structures/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/morpho-org%2Fmorpho-data-structures/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/morpho-org","download_url":"https://codeload.github.com/morpho-org/morpho-data-structures/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/morpho-org%2Fmorpho-data-structures/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269990118,"owners_count":24508817,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-12T02:00:09.011Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-structures","doubly-linked-list","heap","solidity"],"created_at":"2025-03-08T10:00:23.282Z","updated_at":"2025-08-12T02:35:36.697Z","avatar_url":"https://github.com/morpho-org.png","language":"Solidity","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Morpho Data Structures 🦋\n\nThis repository contains the data structures that are used in Morpho Optimizer's matching engine.\nThe data structures are built to be secure and gas efficient.\n\n## Double Linked List\n\nThe 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.\nWhat you can do with it:\n\n- Insert an address sorted by a value passed along this address.\n- Insert (and its value) before an account.\n\n## Red Black Binary Tree\n\nA [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))`.\nOur 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).\nOur modified version makes keys unique items instead of just (key, value) unique pairs.\n\nIn 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.\n\n## Heap based ordering\n\nThis 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.\n\nAt 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.\n\nThe 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.\nIndeed, 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.\nRemoving 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.\nThe main entry point is the `update` function, calling internally either `insert`, `increase`, `decrease` or `remove`.\n\n## Other data structures\n\nOther data structures may be explored in the future and we are open to any suggestions or optimization of current implementations ⚡️\n\n# Audits\n\nThe 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).\n\n# Licenses \n\nThe data structures are licensed under `AGPL-3.0-only`, see [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmorpho-org%2Fmorpho-data-structures","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmorpho-org%2Fmorpho-data-structures","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmorpho-org%2Fmorpho-data-structures/lists"}