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)

Searching Database…

132 ·GitHub
Hush
Что это?Hush — открытая бета приватной программируемой почты на базе идентификации Stellar. Отправитель должен выполнить политику, выбранную получателем (доверенный доступ, верификация, явное одобрение или почтовый сбор), прежде чем письмо будет доставлено, а система создаёт проверяемые квитанции о доставке.
Это почтовый сервис, в котором регистрируешься, или то, что запускаешь сам?Это стек для самостоятельного запуска, а не сервис по регистрации: клиент, API, релей, протокол и смарт-контракты Soroban лежат в этом репозитории, а проверяемой публичной хостед-демо сейчас нет.
Как запустить его локально?Установите Node.js 24+ и Bun 1.3.14, затем запустите dev-сервер Vite — он выведет локальный URL. Отдельная сборка или тестирование контрактов Soroban требуют Rust версии, закреплённой в rust-toolchain.toml.
Нужен ли настоящий кошелёк Stellar или продакшен-учётные данные для тестирования?Нет — локальный профиль по умолчанию использует тестовые аккаунты и синтетические сообщения на тестнете; в документации прямо сказано не использовать реальные seed-фразы кошелька, продакшен-токены или приватные ключи.
Есть ли уже живая продакшен-версия, через которую сегодня можно отправлять настоящие письма?Нет. Hush — прямо заявленная бета, а деплой на тестнет не означает продакшен-доступность, доставляемость или финансовые гарантии; некоторые федерационные домены и идентификаторы пока остаются легаси в ожидании миграции.
Не становятся ли мои письма публичными из-за хранения доставки на Stellar?Нет — тела писем и вложения не попадают в блокчейн: их передают релеи и зашифрованное объектное хранилище; в Stellar касаются только идентификация, политика, почтовый сбор и доказательства доставки, и эти метаданные (связи аккаунтов, суммы платежей, тайминги) всё равно видны в блокчейне.
Как на самом деле работает система одобрения отправителей?Это зависит от политики, настроенной получателем: отправителя могут пропустить через доверенную или верифицированную личность, заставить ждать явного одобрения, попросить оплатить почтовый сбор или заблокировать сразу; клиент показывает происхождение отправителя и статус доставки для каждого письма.
Почему это построено на Stellar, а не на обычном почтовом сервере?Stellar используется чисто как программируемый слой идентификации и доказательств протокола — контракты Soroban обеспечивают политику отправителей, почтовый сбор и квитанции, — так что правила допуска и подтверждения доставки можно проверить независимо, а не доверять одному оператору.
Что ещё на самом деле лежит в репозитории, кроме интерфейса входящих?В него входят разрешение идентификации/федерации Stellar, код шифрования конвертов сообщений и выведения ключей, релей вместе с сервисом зашифрованного объектного хранилища, UI/API инспектора доказательств, а также контракты Soroban для политики, почтового сбора и квитанций.
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