= Lapis Net
image:https://img.shields.io/github/actions/workflow/status/lapisproject-dev/Lapis-Net/ci.yml?branch=master&label=CI&logo=github[CI,link=https://github.com/lapisproject-dev/Lapis-Net/actions/workflows/ci.yml]
image:https://img.shields.io/badge/Kotlin-2.4.20-7F52FF.svg?logo=kotlin&logoColor=white[Kotlin 2.4.20,link=https://kotlinlang.org]
image:https://img.shields.io/badge/JDK-25-ED8B00.svg?logo=openjdk&logoColor=white[JDK 25,link=https://adoptium.net]
image:https://img.shields.io/github/license/lapisproject-dev/Lapis-Net[Apache 2.0,link=https://github.com/lapisproject-dev/Lapis-Net/blob/master/LICENSE]
image::docs/images/ln-banner.png[Lapis Net,link=https://github.com/lapisproject-dev/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 https://github.com/lapisproject-dev/Lapis-Cloud[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, F2 and G) carries direct messages,
mail and call signals through circuits; call media still connects directly and reveals your IP address, so calls are
off in anonymity mode unless --anonymity-allow-call-media=true; the rest of the network layer still shows your IP
address to peers. Since unreleased wave V0.10.0-H message sizes and timing are padded against a local observer
(--anonymity-padding=standard|off), which is not protection against an observer of both ends.
See link:docs/anonymity.adoc[docs/anonymity.adoc]. No external cryptographic or anonymity review has taken place;
link:docs/external-review.adoc[docs/external-review.adoc] prepares one.
- 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
link:docs/status.adoc[docs/status.adoc]; the release history is in link:docs/roadmap.adoc[docs/roadmap.adoc].
== More documentation
- link:docs/status.adoc[Status]: what each wave added, and the known, deliberate gaps.
- link:docs/modules.adoc[Modules]: what each Gradle module does.
- link:docs/comparison.adoc[Comparison]: Lapis Net next to five other decentralized social protocols.
- link:docs/running.adoc[Running a node]: node options and running from source in detail.
- link:docs/architecture.adoc[Architecture], link:docs/roadmap.adoc[Roadmap],
link:docs/anonymity.adoc[Anonymity design], link:docs/releasing.adoc[Releasing].
== Running a node
[source,bash]
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
link:docs/running.adoc[docs/running.adoc].
== Building
[source,bash]
./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 link:docs/running.adoc#_building_and_running_from_source[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 <>) if none
are attached.
Prerequisite: JDK 25 on the PATH or in JAVA_HOME.
[source,bash]
unzip lapis-net-browser-.zip
lapis-net-browser-/bin/lapis-net-browser # node plus minimal browser UI, see Building
unzip lapis-net-cli-.zip
lapis-net-cli-/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 link:docs/running.adoc#_building_and_running_from_source[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):
[source,bash]
Linux
sha256sum -c --ignore-missing SHA256SUMS
macOS (shasum has no --ignore-missing, so select the line of your file)
awk '$2 == ""' SHA256SUMS | shasum -a 256 -c -
The artifacts are not signed; the checksums only detect corrupted downloads. How releases are built and
published: link:docs/releasing.adoc[docs/releasing.adoc].
== Development conventions
See link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] (code standards, documentation rules) and
link:docs/architecture.adoc[docs/architecture.adoc].
== License
Apache License 2.0 — see link:LICENSE[LICENSE].
== Contributing
See link:CONTRIBUTING.adoc[CONTRIBUTING.adoc].
