hush README

The project's README from github.com/Stellar-hush/hush. As one markdown file: README.md.

Hush — private, programmable mail on Stellar

Your inbox. Your rules. Proof for every delivery.

CI MIT License

Review item Current status
License MIT; see LICENSE
Development Local application and testnet development paths; beta software
Hosted experience No verified public Hush demo URL yet; the screenshot-like panel below is an illustration
CI / deployment Check the latest CI run and deployment notes; CI success and deployment are separate
Contributions Public issues and pull requests are welcome; see CONTRIBUTING.md

Hush is an open-source beta for private email built around Stellar identity and programmable inbox access. Mailbox owners can decide how unfamiliar senders reach them: allow a verified identity, request approval, require postage, or block the sender. Encrypted message content stays off-chain; Stellar is used for identity and verifiable protocol actions.

Project status: beta. The application, API, relay, protocol, and Soroban contracts are in this repository. Local development and testnet paths are available. Production readiness and a public hosted demo are separate deployment milestones; check the deployment status before relying on any endpoint.

Hush product and visual identity overview

Product and design overview. The message flow is conceptual and does not claim that a hosted mail service is available.

Why Hush exists

Email makes it easy for anyone to contact an inbox, but the recipient has few tools to set admission rules before a message arrives. Hush explores a different model: senders present verifiable identity and meet the policy selected by the recipient. That can make abuse more costly, give recipients better control, and make delivery claims easier to inspect.

Hush is not a replacement for Stellar wallets and does not put private message bodies on-chain. The Stellar layer supports identity, policy, postage, receipts, and lifecycle evidence. Relays and encrypted object storage carry message payloads.

How a message flows

  1. Resolve the sender. A Hush address or Stellar account is resolved to an identity and the keys needed by the client.
  2. Evaluate the recipient’s rules. The sender learns which admission requirements apply, such as trusted-sender access, verification, explicit approval, or postage.
  3. Encrypt and submit. The client prepares an encrypted envelope and sends it through the relay or configured storage path.
  4. Record protocol evidence. Where the configured chain adapter is enabled, postage and delivery state can be associated with Stellar contract records and receipts.
  5. Inspect the result. The recipient can review sender provenance, delivery state, and available proof details in the client.
flowchart LR
  S[Sender client] --> I[Identity resolution]
  I --> P[Recipient policy]
  P -->|allowed / approval / postage| E[Encrypt envelope]
  E --> R[Relay and encrypted storage]
  E --> C[Stellar / Soroban evidence]
  R --> D[Recipient client]
  C --> D
  D --> V[Verify provenance and receipt]

This diagram describes the intended protocol path. Which steps are active depends on the runtime profile and configured adapters; local demos use synthetic data and are not evidence of a production mail service.

Product capabilities in this beta

Area What the repository contains Where to look
Inbox and sender requests Mailbox views, message actions, sender review, and recipient policy flows src/features/mail/, src/features/requests/
Identity Stellar account and federation resolution, wallet linking, and sender provenance src/features/identity/, src/services/stellar/
Encryption Message-envelope, attachment, key-derivation, and recipient wrapping code with synthetic vectors src/services/crypto/, protocol/messages/
Relay and storage Message submission, relay authentication, encrypted object storage, and delivery state src/services/relay/, src/services/storage/
Stellar contracts Soroban contracts for sender policy, postage, receipts, and message lifecycle contracts/soroban/
Proof inspection UI and API types for inspecting sender and delivery evidence src/features/proof-inspector/, src/server/api/

These are implementation areas, not a promise that every feature is available in a shared hosted environment. Some paths require testnet configuration, operator-managed services, or secrets and are intentionally not enabled in public demos.

Try the project

Local application

Requirements: Node.js 24 or newer and Bun 1.3.14. Rust is needed to build or test the Soroban contracts; use the version pinned in rust-toolchain.toml.

git clone https://github.com/Stellar-hush/hush.git
cd hush
bun install --frozen-lockfile
cp .env.example .env
bun run dev

The Vite development server prints the local URL when it starts. The default development profile is intended for local work and uses development adapters. Use test accounts and synthetic messages. Do not paste wallet seeds, real user content, production tokens, or private keys into .env, fixtures, screenshots, logs, issues, or pull requests.

Useful commands

bun run format:check       # formatting
bun run lint               # lint
bun x tsc --noEmit         # TypeScript types
bun run test               # unit tests
bun run build              # production bundle / worker build

Contract-focused work should also run the relevant commands in contracts/soroban/. See contributor setup for the repository workflow and security verification for security-specific checks.

Documentation map

Stellar and Soroban

Hush uses Stellar as a programmable identity and protocol-evidence layer. Soroban contracts in this repository define policy, postage, receipts, and lifecycle behavior. The client and services include adapters that connect those contracts to message admission and delivery flows. Contract code, deployment manifests, and environment configuration have distinct roles; a local contract build is not proof that a contract is deployed or that a live application is using it.

The system is designed to keep message bodies and attachments out of public ledger state. Ledger transactions and contract events can still reveal operational metadata such as account relationships, payment amounts, timing, and public contract activity. Review the metadata policy before handling sensitive data.

Contributing

Good contribution areas include protocol interoperability vectors, contract failure-path coverage, relay reliability, accessible inbox and sender-request flows, and clear operator documentation. Wave issues should be bounded, independently testable, and possible to complete without production credentials or private user data.

Start with CONTRIBUTING.md, then read the relevant module guide. The project uses a review-first workflow: discuss large changes in an issue, keep changes focused, include exact validation results, and never add secrets or real message content to the repository.

Hush has an MIT license; see LICENSE. Participation in the Stellar Wave is subject to organizer approval and the program’s current rules. The maintainer guide explains how to apply a public repository, add issues after approval, and manage contributor assignments.

Beta boundaries

License

Hush is distributed under the MIT License.

hush (Stellar-hush/hush)

stellar
Searching Database…

132 ·GitHub
Hush
What is this?Hush is an open-source beta for private, programmable email built on Stellar identity. Senders must satisfy a recipient-chosen policy (trusted access, verification, explicit approval, or postage) before a message is delivered, and the system produces verifiable delivery receipts.
Is this a hosted email service I sign up for, or something I run myself?It is a self-run stack, not a signup service: the client, API, relay, protocol and Soroban smart contracts all live in this repo, and there is currently no verified public hosted demo.
How do I get it running locally?Install Node.js 24+ and Bun 1.3.14, then start the Vite dev server, which prints the local URL. Building or testing the Soroban contracts separately requires Rust at the version pinned in rust-toolchain.toml.
Do I need a real Stellar wallet or production credentials to test it?No — the default local profile uses test accounts and synthetic messages against testnet; you're explicitly told not to use real wallet seeds, production tokens, or private keys.
Is there a live, production-ready version I can send real email through today?No. Hush is explicitly beta software, and a testnet deployment is not production availability, deliverability, or a financial guarantee; some federation domains and identifiers are also still legacy pending migration.
Does putting message delivery on Stellar make my emails public?No — message bodies and attachments stay off the ledger, carried by relays and encrypted object storage; only identity, policy, postage and receipt evidence touch Stellar, and that metadata (account relationships, payment amounts, timing) is still visible on-chain.
How does the sender-approval system actually work?It depends on the recipient's configured policy: a sender can be let through via a trusted or verified identity, required to wait for explicit approval, asked to pay postage, or blocked outright, with the client showing sender provenance and delivery state for every message.
Why build this on Stellar instead of a normal mail server?Stellar is used purely as a programmable identity and protocol-evidence layer — Soroban contracts enforce sender policy, postage, and receipts — so admission rules and delivery proofs can be independently verified instead of trusted to a single operator.
What's actually inside the repo besides the inbox UI?It bundles Stellar identity/federation resolution, message-envelope and key-derivation encryption code, a relay plus encrypted object storage service, a proof-inspector UI/API, and the Soroban contracts for policy, postage and receipts.
What are similar projects?stellar-trade, clearledger, nuvex, clearledger-contracts, TrustMint, sphere-sdk, stellar-pathfinder, solana-classic
Which topics is it in?soroban, stellar, beta, end-to-end-encryption, smart-contracts, decentralized, cryptography, web3, messaging, privacy-first, blockchain, email
Creator
Stellar-hush
Size
206 MB
Stars
132
Updated
CommitOct 12
Age
10d
Commits · 90 Days