{"id":24196530,"url":"https://github.com/dedis/onet","last_synced_at":"2025-09-21T21:31:55.572Z","repository":{"id":46680616,"uuid":"76370943","full_name":"dedis/onet","owner":"dedis","description":"Overlay Network for distributed protocols","archived":false,"fork":false,"pushed_at":"2023-02-25T05:09:35.000Z","size":2357,"stargazers_count":50,"open_issues_count":45,"forks_count":29,"subscribers_count":18,"default_branch":"master","last_synced_at":"2024-10-22T12:26:13.587Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dedis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-12-13T15:22:47.000Z","updated_at":"2024-05-27T10:43:33.000Z","dependencies_parsed_at":"2024-06-18T15:27:27.475Z","dependency_job_id":"c15e8dbc-3e06-451d-a1cd-5dcb08416467","html_url":"https://github.com/dedis/onet","commit_stats":null,"previous_names":[],"tags_count":53,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dedis%2Fonet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dedis%2Fonet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dedis%2Fonet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dedis%2Fonet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dedis","download_url":"https://codeload.github.com/dedis/onet/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":233798281,"owners_count":18731954,"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","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":[],"created_at":"2025-01-13T19:35:44.142Z","updated_at":"2025-09-21T21:31:50.077Z","avatar_url":"https://github.com/dedis.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/dedis/onet.svg?branch=master)](https://travis-ci.org/dedis/onet)\n[![Go Report Card](https://goreportcard.com/badge/github.com/dedis/onet)](https://goreportcard.com/report/github.com/dedis/onet)\n[![Coverage Status](https://coveralls.io/repos/github/dedis/onet/badge.svg)](https://coveralls.io/github/dedis/onet)\n[![Codacy Badge](https://api.codacy.com/project/badge/Grade/11ec79aa77fe41748edfdfcd55e92fab)](https://www.codacy.com/manual/nkcr/onet?utm_source=github.com\u0026utm_medium=referral\u0026utm_content=dedis/onet\u0026utm_campaign=Badge_Grade)\n\n# The Cothority Overlay Network Library - Onet\n\nThe Overlay-network (Onet) is a library for simulation and deployment of\ndecentralized, distributed protocols. This library offers a framework for\nresearch, simulation, and deployment of crypto-related protocols with an emphasis\non decentralized, distributed protocols. It offers an abstraction for tree-based\ncommunications between thousands of nodes and it is used both in research for\ntesting out new protocols and running simulations, as well as in production to\ndeploy those protocols as a service in a distributed manner.\n\n**Onet** is developed by [DEDIS/EFPL](http://dedis.epfl.ch) as part of the\n[Cothority](https://github.com/dedis/cothority) project that aims to deploy a\nlarge number of nodes for distributed signing and related projects. In\ncothority, nodes are commonly named \"conodes\". A collective authority\n(cothority) is a set of conodes that work together to handle a distributed,\ndecentralized task.\n\nOnet allows you to set up the following three elements:\n\n-   _protocols_: a short-lived set of messages being passed back and forth between\n    one or more conodes\n\n-   _services_: define an API usable by client programs and instantiate protocols\n\n-   _apps_: communicate with the service-API of one or more conodes\n\nWe also provide a set of methods to set up and run _simulations_.\n\n* * *\n\n\u003c!-- START doctoc.sh generated TOC please keep comment here to allow auto update --\u003e\n\n\u003c!-- DO NOT EDIT THIS SECTION, INSTEAD RE-RUN doctoc.sh TO UPDATE --\u003e\n**:book: Table of Contents**\n\n-   [The Cothority Overlay Network Library - Onet](#the-cothority-overlay-network-library---onet)\n-   [General information](#general-information)\n    -   [Directories](#directories)\n    -   [Version](#version)\n    -   [License](#license)\n    -   [Contribution](#contribution)\n    -   [Contact](#contact)\n    -   [Reporting security problems](#reporting-security-problems)\n-   [Components](#components)\n    -   [Router](#router)\n    -   [Conode](#conode)\n    -   [Roster](#roster)\n    -   [Protocol](#protocol)\n    -   [Service](#service)\n    -   [ServiceManager](#servicemanager)\n    -   [Tree](#tree)\n    -   [Overlay](#overlay)\n    -   [TreeNodeInstance](#treenodeinstance)\n    -   [App](#app)\n-   [Database Backup and Recovery](#database-backup-and-recovery)\n    -   [Backup](#backup)\n    -   [Recovery](#recovery)\n    -   [Interacting with the database](#interacting-with-the-database)\n-   [Simulation](#simulation)\n\n\u003c!-- END doctoc.sh generated TOC please keep comment here to allow auto update --\u003e\n\n# General information\n\n## Directories\n\n-   [app](app) - useful libraries if you want to create a CLI app for the\n    cothority\n\n-   [cfgpath](cfgpath) - single package to get the configuration-path\n\n-   [log](log) - everybody needs its own log-library - this one has log-levels,\n    colors, time, ...\n\n-   [network](network) - different type of connections: channels, tcp, tls\n\n-   [simul](simul) - allowing to run your protocols and services on different\n    platforms with up to 50'000 nodes\n\n## Version\n\nThe Onet library follows the same development cycle as the one described in\nthe [dedis/cothority](https://github.com/dedis/cothority/tree/master/) project.\n\n## License\n\nThis project and all its files are licensed under the\nGNU Lesser General Public License, version 3 (SPDX short identifier: LGPL-3.0)\n\nIf this license is not suitable for your business or project\nplease contact us for a full commercial license.\n\n## Contribution\n\nIf you want to contribute, please have a look at\n[CONTRIBUTION](https://github.com/dedis/onet/blob/master/CONTRIBUTION) for\nlicensing details and feel free to open a pull request.\n\n## Contact\n\nYou can contact us at \u003chttps://groups.google.com/forum/#!forum/cothority\u003e or\nprivately at dedis@epfl.ch.\n\n## Reporting security problems\n\nThis library is offered as-is without any guarantees. It would need an\nindependent security review before it should be considered ready for use in\nsecurity-critical applications. If you integrate Onet into your application it\nis YOUR RESPONSIBILITY to arrange for that audit.\n\nIf you notice a possible security problem, please report it\nto dedis-security@epfl.ch.\n\n# Components\n\nIn Onet, you define _Services_ that use _Protocols_ which can send and receive\nmessages. Each _Protocol_ is instantiated when needed as a _ProtocolInstance_.\nAs multiple _Protocols_ can be run at the same time, there can be more than one\n_ProtocolInstance_ of the same _Protocol_. Onet makes sure all messages get\nrouted to the appropriate _ProtocolInstance_.\n\nForeign applications can communicate with Onet over the service-API, which is\nimplemented using protobuf over WebSockets for JavaScript compatibility.\n\nThis chapter provides a high-level description of the cothority framework. Let's\nstart with a picture and then dive into each main components of the\nlibrary.\n\n![system overview](http://www.plantuml.com/plantuml/proxy?cache=no\u0026src=https://raw.githubusercontent.com/dedis/onet/master/docs/diagrams/components.iuml)\n\nAs you can see there's a bunch of different entities involved. Let's get down\nthe rabbit hole to explain the most important ones!\n\n## Router\n\nThe Router handles all incoming and outgoing messages from and to the network. A\nRouter can use different underlying types of connection: \n\n-   _TCP_ which uses regular TCP connections, \n-   _Local_ which uses channels and is mainly for testing purposes, and \n-   _TLS_ which is still in progress.\n\n## Conode\n\nA conode is the main entity of a Cothority server. It holds the Router, the\nOverlay, and the different Services. Generally, for developing an application\nusing the framework, you would create your Router first, then the Conode, and\nthen finally call `conode.Start()`.\n\n## Roster\n\nA Roster is simply a list of Conodes denoted by their public key and address. A\nRoster is identified by its ID, which is unique for each list.\n\n## Protocol\n\nA Protocol is an interface where users of the library must implement the logic\nof the protocol they want to code. It is supposed to be a short term entity that\nis self-sufficient, i.e. it does not need external access to any other resources\nof the Cothority framework. A protocol can be launched from SDA itself or by a\nService.\n\n## Service\n\nA Service is a long term entity that is created when a Conode is created. It\nserves different purposes:\n\n-   serving external client requests,\n-   creating and attaching protocols with the Overlay (and launching them),\n-   communicating information to other Services on other Conodes.\n\n## ServiceManager\n\nA ServiceManager is the main interface between the Conode and the Service. It\ntransforms  and embed the messages created by the Service to its own format and\npass it to the Conode for the sending part; vice versa for the reception part.\n\n## Tree\n\nA Tree is a standard tree data structure where each node - called\n_TreeNode_ - is denoted by its public key and address. The Tree is constructed\nout of a Roster.\n\n## Overlay\n\nThe Overlay provides an abstraction to communicate over different Trees that the\nProtocols and Services need. It handles the following tasks:\n\n-   Propagations of the Roster and the Trees between different Conodes\n-   Creation of the Protocol\n-   Dispatching of incoming and outgoing messages to the right Protocol\n\n## TreeNodeInstance\n\nA TreeNodeInstance is created by the Overlay. There is one TreeNodeInstance for\neach Protocol and it acts as the central point of communication for that\nProtocol. The TreeNodeInstance offers to its Protocol some common tree methods\nsuch as `SendParent`,`SendChild`, `IsRoot` etc. More importantly, it transforms\nand embeds the message given by the Protocol into its own struct and dispatch it\nto the Overlay for the sending part; vice versa for the reception part.\n\n## App\n\nAn application in the context of Onet is a CLI-program that interacts with one\nor more conodes through the use of the API defined by one or more services. It\nis mostly written in go, but in the cothority-repository you can also find\nlibraries to interact in javascript and java.\n\n# Database Backup and Recovery\n\nUsers of Onet have the option to make use of its built-in database.\n\nWe use [bbolt](https://github.com/etcd-io/bbolt), which supports \"fully\nserializable ACID transactions\" to ensure data integrity for Onet users. Users\nshould be able to do the following:\n\n-   Backup data while Onet is running\n-   Recovery from a backup in case of data corruption\n\n## Backup\n\nUsers are recommended to perform frequent backups such that data can be\nrecovered if Onet nodes fail. Onet stores all of its data in the context folder,\nspecified by `$CONODE_SERVICE_PATH`. If unset, it defaults to\n\n-   `~/Library/Application Support/conode/data` on macOS,\n-   `$HOME\\AppData\\Local\\Conode` on Windows, or\n-   `~/.local/share/conode` on other Unix/Linux.\n\nHence, to backup, it is recommended to use a standard backup tool, such as\nrsync, and copy the folder to a different physical location periodically.\nThe database keeps a transaction log.\n\nPerforming backups in the middle of a transaction should not be a problem.\nHowever, it is still recommended to check the data integrity of the backed-up\nfile using the bbolt CLI, i.e. `bolt check database_name.db`.\n\nTo install the bbolt CLI, see [Bolt Installation](https://github.com/etcd-io/bbolt#installing).\n\n## Recovery\n\nData corruption is easy to detect as Onet nodes crash when reading from a\ncorrupted database, at startup or during operation. Concretely, the bbolt\nlibrary would panic\n([source](https://github.com/etcd-io/bbolt/blob/386b851495d42c4e02908838373a06d0a533e170/freelist.go#L237)).\nThis behavior is produced by writing a few blocks of random data using `dd` to\nthe database.\n\nIn case of data corruption, the database must be restored from a backup by\nsimply copying the backup copy to the context directory, and then starting the\nconode again. It is the user's responsibility to make sure that the data is up\nto date, e.g. by reading the latest data from running Onet nodes.\n\n## Interacting with the database\n\nThe primary and recommended methods to interact with the database are\n[`Load`](https://godoc.org/github.com/dedis/onet#Context.Load) and\n[`Save`](https://godoc.org/github.com/dedis/onet#Context.Save). If more control\non the database is needed, then we can ask the context to return a database\nhandler and bucket name using the function\n[`GetAdditionalBucket`](https://godoc.org/github.com/dedis/onet#Context.GetAdditionalBucket).\n\nAll the [bbolt functions](https://godoc.org/github.com/etcd-io/bbolt) can be\nused with the database handler. However, the user should avoid creating new\nbuckets using the bbolt functions and only use `GetAdditionalBucket` to avoid\nbucket name conflicts.\n\n# Simulation\n\nHave a look at the `simul/README.md` for explanations about simulations.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdedis%2Fonet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdedis%2Fonet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdedis%2Fonet/lists"}