Metadata-Version: 2.4
Name: lapsecoin
Version: 0.8.16
Summary: LapseCoin full node: Falcon-512 post-quantum signatures, a VDF-based consensus clock, and a built-in wallet dashboard.
License-Expression: MIT
Project-URL: Homepage, https://github.com/Lapsecoin/core
Project-URL: Repository, https://github.com/Lapsecoin/core
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: argcomplete>=3.2
Requires-Dist: cachetools>=5.3
Requires-Dist: chiavdf>=1.1.14
Requires-Dist: flask>=3.0
Requires-Dist: flask-limiter>=3.5
Requires-Dist: liboqs-python>=0.14.0
Requires-Dist: libtorrent>=2.0.0
Requires-Dist: markdown>=3.5
Requires-Dist: msgpack>=1.0
Requires-Dist: orjson>=3.9
Requires-Dist: peewee>=3.17
Requires-Dist: Pillow>=10.0
Requires-Dist: PyNaCl>=1.5
Requires-Dist: pystray>=0.19
Requires-Dist: requests>=2.31
Requires-Dist: stellar-sdk>=13.0
Requires-Dist: waitress>=3.0
Dynamic: license-file

<div align="center">
  <img src="lapsecoin.svg" width="120" alt="LapseCoin logo" />

  # LapseCoin

  Peer-to-peer electronic cash, secured by a Verifiable Delay Function instead of proof-of-work mining, with quantum-resistant signatures.

  [![Release](https://img.shields.io/github/v/release/Lapsecoin/core)](https://github.com/Lapsecoin/core/releases)
  [![Live node](https://img.shields.io/badge/node-lapsenode.vicnas.me-2ea44f)](https://lapsenode.vicnas.me/)
  [![Whitepaper](https://img.shields.io/badge/docs-whitepaper-blue)](docs/whitepaper.md)
  [![Donate BTC](https://img.shields.io/badge/donate-BTC-f7931a)](#support)
  [![Discord](https://img.shields.io/badge/discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/FP2d8JmK6r)
</div>

**Recommended: use a pre-built release.** Building from source requires native libraries (liboqs, chiavdf) that involve complex C/C++ compilation and can produce DLL or shared library errors depending on your platform. The release binaries on the [releases page](https://github.com/Lapsecoin/core/releases) are self-contained and require no dependencies.

Join the [Discord](https://discord.gg/FP2d8JmK6r) for discussions, news, and trades with other coins.

## Quick start

Grab a binary from the [releases page](https://github.com/Lapsecoin/core/releases), self-contained with no dependencies.

```
# Linux                    # Windows
chmod +x lapsecoin         lapsecoin.exe
./lapsecoin
```

You'll be prompted for a signing passphrase, then the wallet is at `http://localhost:8335` and the block explorer at `http://localhost:8333`.

For headless environments (Docker/systemd/CI, no GUI), set the passphrase non-interactively and pass `--no-gui`:

```bash
export LAPSECOIN_PASSPHRASE="your passphrase"
./lapsecoin --no-gui
```

## Light client (lapsecoin-dumb)

A wallet and the board with no chain of its own, for a small data allowance, a small disk, or a machine that cannot keep a node running. It holds your key and signs on your machine, and asks a node's public API for everything else. A session of looking at the board, sending, and posting costs a few kilobytes. It has the full node's Board, Balance and Send pages, including editing and deleting your own posts.

```
./lapsecoin-dumb          # or lapsecoin-dumb.exe on Windows
```

It asks for the key's passphrase, then opens the wallet at `http://127.0.0.1:8335/`. A key from the full node works as is. There is nothing to configure. Options, none needed: `--node URL` to ask a node you run (repeatable), `--refresh SECONDS` to reuse answers for longer and use less data, `--proxy auto|none|URL` (default `auto`, below).

### What the node you ask can learn

The node is trusted for what the chain says: it can show a wrong balance or hide a transaction, but it can never spend your coins, because signing happens only on your machine. Reading the board names nobody. Looking up a balance, or sending, posting, voting, editing or deleting, names your wallet address, and a node answering also sees the IP that asked. So those go by the most private route there is, and the page header says which:

1. **Tor**, if it is running on your machine (the daemon or Tor Browser). It is used when found and dropped when not, with nothing to set up. The node never sees your IP.
2. **A relay**, when two nodes support it. Your request is sealed to one node and handed over by another: the one that sees your IP gets only sealed bytes, and the one that reads the request sees only the relay. A transaction is then in the same position as one a node submits for itself, whose origin the network's Dandelion relay already hides. It costs about a kilobyte more per request. It protects you unless the two nodes are the same operator or compare notes.
3. **Directly** to the node, the last resort, when neither is available. That node then sees your IP and your address together. A node you run yourself (`--node`) is the way to make that your own business.

Nothing is ever refused for lack of a private route. `--proxy none` never uses a proxy, and a proxy URL always uses that one.

### How the board works without a chain

The full node reads the whole chain once, resolves the board (threads, replies, votes, profiles, edits and deletes) and serves the result as a small JSON document. The light client fetches that and renders it with the same page code the full node uses. For ten threads it is about 1.2 KB compressed, and a board that has not changed since the last request costs a 304 with no body. The board is not checked against the chain, since the client has none, so a dishonest node could show a board that differs from it. It cannot make you sign anything, and your own posts, votes, edits and deletes are signed on your machine.

<details>
<summary>Serving your node over HTTPS</summary>

A node speaks plain HTTP, and peers are bare `ip:port` addresses with no name for a certificate to be issued to. To offer an encrypted connection, put a reverse proxy with a domain in front of the node's web port and tell the node its address:

```
# Caddy: fetches and renews the certificate by itself
mynode.example.org {
    reverse_proxy 127.0.0.1:8333
}
```

```
lapsecoin --public-url https://mynode.example.org     # or LAPSECOIN_PUBLIC_URL
```

The node then advertises that address (`/api/info`), its peers pass it on to light clients, and light clients prefer it when they send their wallet address directly. The proxy should add the client's address to `X-Forwarded-For` (Caddy does); the node believes that header only from the machine it runs on, so clients keep separate rate limits and no one else can choose theirs. The node's port stays open for peers as before. Only a domain name is accepted, never an IP address.

A node also passes light clients' sealed requests on to its peers, and opens ones sealed to it, which is what lets a client keep its address from the node that sees its IP (above). It never sees what is inside a request it passes on, only forwards to peers it already knows, and rate-limits callers. `--no-relay` turns it off.

</details>

<details>
<summary>How consensus works</summary>

Most cumulative proven work wins, Bitcoin-style. Two blocks at the same height carry equal work, so that tie goes to the lower VDF output, not to whichever arrived first. A height stays open to a better sibling for a few seconds (`LAPSECOIN_DRAW_WINDOW_SECONDS`) so the comparison can happen; work on the next height never stops meanwhile.

Block timing is enforced by a VDF anchored to real elapsed time, believed to have a much smaller hardware-advantage gap than proof-of-work. Transactions are ordinary and plaintext, with sender-bid fees, much like Bitcoin's own. Signatures are FALCON-512 (quantum-resistant). Full spec in [docs/whitepaper.md](docs/whitepaper.md).
</details>

<details>
<summary>Running from source</summary>

Requires Python 3.11+.

**Linux/macOS:**

```bash
curl -fsSL https://raw.githubusercontent.com/Lapsecoin/core/main/scripts/install.sh | bash
```

**Windows (PowerShell):**

```powershell
irm https://raw.githubusercontent.com/Lapsecoin/core/main/scripts/install.ps1 | iex
```

Then: `lapsecoin`. Installs build tools if missing, then the app; falls back to skipping `libtorrent` (with a starter peers list) only if that's what fails.
</details>

<details>
<summary>Building the binary yourself</summary>

```
pip install pyinstaller cairosvg Pillow miniupnpc
make linux    # on Linux
make windows  # on Windows
```

Produces a self-contained binary in `dist/`. Requires cmake, ninja, and a C compiler (on Windows, also liboqs and MSVC redistributables).
</details>

<details>
<summary>Updating, and when it isn't optional</summary>

A node too old to speak the current wire format is refused at the handshake, so it sits alone mining a chain nobody sees. Old formats aren't carried forever, so some updates are mandatory. The version number says which:

| Change | Example | What it means |
|---|---|---|
| Third number | `0.6.0` to `0.6.1` | Fixes. Update when convenient |
| Second number | `0.5.1` to `0.6.0` | **Required.** Wire format changed, older nodes are dropped |
| First number | `0.x` to `1.x` | Consensus break. Required, expect a resync |

Alone with no peers after everyone else updated? Check your version first.
</details>

<details>
<summary>Ports and passphrase</summary>

| | Port | Interface | Purpose |
|---|---|---|---|
| Public | `8333` (`--port`) | `0.0.0.0` | Peer traffic (UDP) and the read-only node UI (TCP). Safe to expose. Send disabled. |
| Private | `port+2` (`--private-port`) | `127.0.0.1` | Wallet UI. **Never expose.** Full access, including Send. |

`port+3` is reserved for the DHT subsystem (libtorrent). Port `18334` is fixed and reserved across every node for same-network peer discovery (broadcast-based, finds other LapseCoin nodes on your LAN automatically regardless of their own port). Don't bind other services to either.

The passphrase is required to start the node. By default you're prompted via `getpass` (nothing touches shell history or `ps`). For Docker/systemd/CI, set it non-interactively instead:

```bash
export LAPSECOIN_PASSPHRASE="your passphrase"
python main.py
```

There is no `--passphrase` flag, since it was removed because it leaked into `ps aux` and shell history.

The peer port can be set the same way, which is often easier than a flag in a container or unit file:

```bash
export LAPSECOIN_PORT=8444
python main.py
```

`--port` still wins if you pass it, so the variable sets the default rather than overriding what you typed. The private port follows from it as usual unless you set `--private-port`.

The log level can be set the same way:

```bash
export LAPSECOIN_LOG_LEVEL=DEBUG
python main.py
```

`--log-level` still wins if you pass it.
</details>

<details>
<summary>Settings and environment variables</summary>

Node-local settings live on the private wallet UI under **Settings**, and each can also be set by environment variable. The environment wins, so a container or unit file can force a value for one launch without overwriting what's saved; a value set that way shows on the page as forced rather than editable.

| Variable | Default | Meaning |
|---|---|---|
| `LAPSECOIN_PASSPHRASE` | prompted | Non-interactive wallet passphrase; also implies `--no-gui` |
| `LAPSECOIN_PORT` | `8333` | Default public HTTP and peer port; `--port` wins when supplied |
| `LAPSECOIN_LOG_LEVEL` | `INFO` | Default log level: `DEBUG`, `INFO`, `WARNING`, or `ERROR` |
| `LAPSECOIN_DOCKER` | unset | Set to `1` inside the project Docker image; disables self-update |
| `LAPSECOIN_PEERS_URL` | project default | Starter peer-list URL used by the installer and update fallback |
| `LAPSECOIN_DRAW_WINDOW_SECONDS` | `10` | Same-height draw window in seconds |
| `LAPSECOIN_SWAP_CONFIRM_DEPTH` | `2` | How many blocks must bury a LapseCoin payment before a swap treats it as settled |
| `LAPSECOIN_SWAP_AUTO_ACCEPT_MIN_TRUST` | `0` | Minimum counterparty trust score for a fill request to auto-accept |
| `LAPSECOIN_SHOW_HARDWARE_DETAILS` | `true` | Show this node's hardware details on the odds page |
| `LAPSECOIN_MINING_ENABLED` | `true` | Enable this node's block building |
| `LAPSECOIN_HIDE_ADDRESS_PUBLICLY` | `true` | Hide this node's address from the public dashboard |

`APPIMAGE` is set by the AppImage runtime itself and is not normally configured by users. `LAPSECOIN_REPO_RAW` is used only by the source installer to override where it downloads `requirements.txt` from.

</details>

<details>
<summary>All CLI options</summary>

| Option | Default | Description |
|---|---|---|
| `--host` | `0.0.0.0` | Interface to bind for the public port |
| `--port` | `8333` | Public port for HTTP API and peer connections |
| `--private-port` | `port+2` | Private port for wallet UI, always bound to 127.0.0.1 |
| `--keyfile` | `lapsecoin_key.json` | Path to encrypted keypair |
| `--db` | `lapsecoin_chain.db` | Path to SQLite chain database |
| `--peer host:port` | - | Bootstrap peer (repeatable) |
| `--max-peers` | `125` | Hard cap on peer table size |
| `--log-level` | `INFO` (or `LAPSECOIN_LOG_LEVEL`) | Verbosity: DEBUG, INFO, WARNING, ERROR. DEBUG adds the HTTP access log |
| `--no-gui` | off | Headless. Implied when `LAPSECOIN_PASSPHRASE` is set |
| `--no-update-check` | off | Don't check for new releases |
| `--update-check-url` | *(project)* | Where to look for the current version |
| `--releases-url` | *(project)* | Where the update notice points people |
</details>

## Exchanges

No LAPSE exchange listings yet.

In the meantime, [Discord](https://discord.gg/FP2d8JmK6r) allows direct trades with XLM, as well as the in-app Market (beta). Default rate is 1 XLM for 1000 LAPSE.
---

<div align="center" id="support">

**Support the project:** BTC `bc1q8qxvr5zuws78650wz9rgzpqxfx7dqzl38rdtsw`

</div>
