Aquadoggo

<div class="warning"> The `aquadoggo` crate has been deprecated, please use the new p2panda stack instead. </div> <h1 align="center">aquadoggo</h1> <div align="center"> <img src="https://raw.githubusercontent.com/p2panda/.github/main/assets/dolphin-left.gif" width="auto" height="30px"> <strong>p2panda network node</strong> <img src="https://raw.githubusercontent.com/p2panda/.github/main/assets/dolphin-right.gif" width="auto" height="30px"> </div> <br /> <div align="center"> <!-- CI status --> <a href="https://github.com/p2panda/aquadoggo/actions"> <img src="https://img.shields.io/github/actions/workflow/status/p2panda/aquadoggo/tests.yml?branch=main&style=flat-square" alt="CI Status" /> </a> <!-- Codecov report --> <a href="https://app.codecov.io/gh/p2panda/aquadoggo/"> <img src="https://img.shields.io/codecov/c/gh/p2panda/aquadoggo?style=flat-square" alt="Codecov Report" /> </a> <!-- Crates version --> <a href="https://crates.io/crates/aquadoggo"> <img src="https://img.shields.io/crates/v/aquadoggo.svg?style=flat-square" alt="Crates.io version" /> </a> </div> <div align="center"> <h3> <a href="https://docs.rs/aquadoggo"> Docs </a> <span> | </span> <a href="https://github.com/p2panda/aquadoggo/releases"> Releases </a> <span> | </span> <a href="https://aquadoggo.p2panda.org/about/contribute/"> Contribute </a> <span> | </span> <a href="https://aquadoggo.p2panda.org"> Website </a> </h3> </div> <br/>

aquadoggo is a reference node implementation for p2panda. It is a intended as a tool for making the design and build of local-first, collaborative p2p applications as simple as possible, and hopefully even a little fun!

aquadoggo can run both on your own device for local-first applications, or on a public server when acting as shared community infrastructure. Nodes like aquadoggo perform a number of tasks ranging from core p2panda data replication and validation, aiding the discovery and establishment of connections between edge peers, and exposing a developer friendly API used for building applications.

Features

• Awaits signed operations from clients via GraphQL.
• Verifies the consistency, format and signature of operations and rejects invalid ones.
• Stores operations of the network in an SQL database of your choice (SQLite, PostgreSQL).
• Materializes views on top of the known data.
• Answers filtered, sorted and paginated data queries via GraphQL.
• Discovers other nodes in local network and internet.
• Establishes peer-to-peer connections via UDP holepunching or via relays.
• Replicates data efficiently with other nodes.

Who is this for?

aquadoggo might be interesting for anyone who wants to participate in a p2p network. This could be as a node maintainer, an application developer or simply someone wanting to learn more about p2p networking in a hands-on fashion.

If you are familiar with (or are keen to learn) how to use command line interfaces then you're able to deploy a node on your own machine, you can then experiment with creating data schemas, publishing and replicating data, and then querying it again using the GraphQL playground. Check out the resources section for ideas on next steps when you're ready.

What can I build with this?

Many applications which rely on being able to store and retrieve data from a persistent store could likely be built using aquadoggo as their data layer. aquadoggo can be considered as a p2p "backend", which takes some of the complexity out of p2p development, leaving you to focus on building applications using your preferred tools.

If you want to build a client application which communicates with an aquadoggo you will need to have some experience with web development or the Rust programming language. For writing an application using Rust you can import aquadoggo directly in your code. If building a TypeScript web frontend which will interface with a local or remote node, you can import the small TypeScript client library shirokuma to your project. We have plans for making it easier to interact with aquadoggo using other languages in the future.

Some example applications which could be built on top of aquadoggo are:

• 🥄 Community centre resource management: Members of the centre want to manage some shared resources (table tennis, tools, cooking equipment), they each run an app (Tauri desktop app with a bundled aquadoggo inside) on their own devices, where they can add resources, view availability and making loan requests. Discovery and syncing of data occurs automatically when member's devices are on the same local network.

  <details> <summary>See config</summary> <br>

  # Schemas needed for our resource management application
  allow_schema_ids = [
      "resource_0020c3accb0b0c8822ecc0309190e23de5f7f6c82f660ce08023a1d74e055a3d7c4d",
      "resource_booking_request_0020aaabb3edecb2e8b491b0c0cb6d7d175e4db0e9da6003b93de354feb9c52891d0",
      "resource_booking_accepted_00209a75d6f1440c188fa52555c8cdd60b3988e468e1db2e469b7d4425a225eba8ec",
  ]
  
  # Enable mDNS discovery to automatically find other nodes on the local network and share data with them
  mdns = true
  

  </details>

• 🐦 Local ecology monitoring: Village residents want to collect data on bird species which are sighted in their area over the year. They want anyone with the app to be able to upload a sighting. All the residents run a native Android app on their smartphone, and they make use of a number of relay nodes which enables discovery and p2p or relayed connection establishment.

  <details> <summary>See config</summary> <br>

  app node config

  # Schemas needed for our ecology monitoring application
  allow_schema_ids = [
      "bird_species_0020c3accb0b0c8822ecc0309190e23de5f7f6c82f660ce08023a1d74e055a3d7c4d",
      "bird_sighting_0020aaabb3edecb2e8b491b0c0cb6d7d175e4db0e9da6003b93de354feb9c52891d0",
  ]
  
  # Addresses of the relay nodes helping us to connect the residents over the internet
  relay_addresses = [
      "203.0.113.1:2022",
      "198.51.100.21:2022",
  ]
  

  relay node config

  # A relay doesn't need to support any schemas
  allow_schema_ids = []
  
  # Enable relay mode
  relay_mode = true
  

  </details>

• 🗞️ Coop notice boards: residents of a group of housing coops want to start a collaborative notice board. Each coop deploys a node on their local network and residents access a web-app to post and view ads or news. They're already using a shared VPN so nodes can connect directly, but only some coops are allowed to join the noticeboard network.

  <details> <summary>See config</summary> <br>

  # Schemas needed for our coop notice board application
  allow_schema_ids = [
      "notice_board_0020c3accb0b0c8822ecc0309190e23de5f7f6c82f660ce08023a1d74e055a3d7c4d",
      "notice_board_post_0020aaabb3edecb2e8b491b0c0cb6d7d175e4db0e9da6003b93de354feb9c52891d0",
  ]
  
  # Addresses of already known nodes we can connect directly to
  direct_node_addresses = [
      "192.0.2.78:2022",
      "198.51.100.22:2022",
      "192.0.2.211:2022",
      "203.0.114.123:2022",
  ]
  
  # Peer ids of allowed peers, these will be the expected identities for the nodes we are connecting
  # directly to
  allowed_peer_ids = [
      "12D3KooWP1ahRHeNp6s1M9qDJD2oyqRsYFeKLYjcjmFxrq6KM8xd",
      "12D3KooWPC9zdWXQ3aCEcxvuct9KUWU5tPsUT6KFo29Wf8jWRW24",
      "12D3KooWDNNSdY8vxYKYZBGdfDTg1ZafxEVuEmh49jtF8rUeMkq2",
      "12D3KooWMKiBvAxynLn7KmqbWdEzA8yq3of6yoLZF1cpmb4Z9fHf",
  ]
  

  </details>

We're excited to hear about your ideas! Join our official chat and reach out.

Installation

Command line application

Check out our Releases section where we publish binaries for Linux, RaspberryPi, MacOS and Windows or read how you can compile aquadoggo yourself.

Rust Crate

For using aquadoggo in your Rust project, you can add it as a dependency with the following command:

cargo add aquadoggo

Usage

Run node

You can also run the node simply as a command line application. aquadoggo can be configured in countless ways for your needs, read our configuration section for more examples, usecases and an overview of configuration options.

# Start a local node on your machine, go to http://localhost:2020/graphql for using the GraphQL playground
aquadoggo

# Check out all configuration options
aquadoggo --help

# Enable logging
aquadoggo --log-level info

Docker

For server deployments you might prefer using Docker to run aquadoggo.

docker run -p 2020:2020 -p 2022:2022 -e LOG_LEVEL=info p2panda/aquadoggo

Embed node

Run the node directly next to the frontend you're building for full peer-to-peer applications by using the aquadoggo Rust crate. Check out our Tauri example for writing a desktop app.

use aquadoggo::{Configuration, Node};
use p2panda_rs::identity::KeyPair;

let config = Configuration::default();
let key_pair = KeyPair::new();
let node = Node::start(key_pair, config).await;

FFI bindings

If you are not working with Rust you can create FFI bindings from the aquadoggo crate into your preferred programming language. Dealing with FFI bindings can be a bit cumbersome and we do not have much prepared for you (yet), but check out our Meli Android project as a