Lapis Net

Lapis Net is a fully decentralized peer-to-peer social network protocol on the Kotlin/JVM platform. It is part of the Lapis family of distributed systems, alongside Lapis Cloud.

The protocol combines:

• Decentralized identity — secp256k1 keypairs, Bitcoin-compatible

• Content-addressed storage — Nabu (IPFS-on-libp2p), DHT + Bitswap

• Web-of-trust reputation — Veritas, a shortest-path trust graph

• Gossip-based propagation — libp2p GossipSub

• Bitcoin/Lightning-anchored micropayment relevance — Virtus (on-chain OP_RETURN and Lightning BOLT-11 payment proofs)

• Sybil-resistant free "likes" — Karma, weighted by Veritas and a Bitcoin time anchor

• Machine-to-machine infrastructure reputation — Madli, a five-metric weighted-median node-reputation layer

The protocol core is deliberately neutral about curation, sorting, and reputation models. Veritas, Karma, Virtus, and Madli (the scoring dimensions) are optional tools for browser/view implementations, not protocol requirements.

Status

Lapis Net is a working prototype. The current release is v0.12.0. There is no public network yet, hardly any users, and connecting two real nodes is still a manual step. Nostr, Mastodon, Bluesky and Farcaster have millions of users and mature client ecosystems; Lapis Net does not.

• Hole punching (dcutr, --hole-punching=auto|on|off) is verified on Linux loopback only. It is not verified behind a real router or CGNAT, on macOS, or on Windows.

• Traffic anonymisation does not anonymise your traffic yet. The onion modules (lapis-net-onion, lapis-net-onion-wire) are a foundation and a wire layer; the experimental, unreleased option --anonymity=on publishes the directory entry and (unreleased waves V0.10.0-F1 and F2) carries direct messages and mail, online and offline, through circuits; call media and the rest of the network layer still show your IP address to peers. See docs/anonymity.adoc.

• There is no embedded Lightning node (proof verification only), no group calls, no video and no multi-device messaging.

The wave-by-wave status table and the complete list of known, deliberate gaps are in docs/status.adoc; the release history is in docs/roadmap.adoc.

More documentation

• Status: what each wave added, and the known, deliberate gaps.

• Modules: what each Gradle module does.

• Comparison: Lapis Net next to five other decentralized social protocols.

• Running a node: node options and running from source in detail.

• Architecture, Roadmap, Anonymity design, Releasing.

Running a node

# headless node behind a NAT: reserves relays, uses the DHT directory (no DM, no mail)
lapisnet node --reachability=private
# browser node: same switches as arguments, LAPISNET_* variables or $LAPISNET_HOME/browser.properties
lapisnet-browser --reachability=private --dm-veritas-gate=true

An invalid option aborts the start. All options, the mail gates and the onion relay switch are in docs/running.adoc.

Building

./gradlew clean check   # compiles, runs tests, runs ktlint
./gradlew :lapis-net-cli:run

Requires JDK 25. To run the reference node together with its minimal browser UI, use ./gradlew :lapis-net-browser:run. State lives under $LAPISNET_HOME (default ~/.lapisnet); the default listen address is loopback-only. Environment variables, connecting two nodes and the port restriction are described in docs/running.adoc.

Download

Releases are listed at https://github.com/lapisproject-dev/Lapis-Net/releases. v0.10.1 is the first release built by the release pipeline, whose publish step was tested only against local stand-ins before that run, not against GitHub itself. Starting with v0.10.1 (the current release is v0.12.0), a release is published together with lapis-net-browser-<version>.zip, lapis-net-cli-<version>.zip and SHA256SUMS. Releases before that, including v0.10.0, have no downloadable files: check the release’s asset list, and build from source (see Building) if none are attached.

Prerequisite: JDK 25 on the PATH or in JAVA_HOME.

unzip lapis-net-browser-<version>.zip
lapis-net-browser-<version>/bin/lapis-net-browser   # node plus minimal browser UI, see Building

unzip lapis-net-cli-<version>.zip
lapis-net-cli-<version>/bin/lapis-net-cli           # multi-node demo, ends by itself after a few seconds

The ZIPs also contain .bat start scripts for Windows; those are not tested. The environment variables described in docs/running.adoc, in particular LAPISNET_HOME and LAPISNET_KEYSTORE_PASSPHRASE, apply to the unpacked distributions as well.

Verify a download against SHA256SUMS, which lists both ZIPs, so the check has to be limited to the file you actually downloaded (<file> is its name, for example lapis-net-cli-<version>.zip):

# Linux
sha256sum -c --ignore-missing SHA256SUMS
# macOS (shasum has no --ignore-missing, so select the line of your file)
awk '$2 == "<file>"' SHA256SUMS | shasum -a 256 -c -

The artifacts are not signed; the checksums only detect corrupted downloads. How releases are built and published: docs/releasing.adoc.

Development conventions

See CONTRIBUTING.adoc (code standards, documentation rules) and docs/architecture.adoc.

License

Apache License 2.0 — see LICENSE.

Contributing

See CONTRIBUTING.adoc.