SafHandle Contract
On-chain short names and phone links for Safrochain

---

Status: Specification / Documentation phase. CosmWasm source code and deployment artifacts will be added in a follow-up milestone. This repository defines the on-chain registry design and open-source project structure.

SafHandle lets users send SAF to short names like john.saf or phone numbers like +243899123456 instead of long addr_safro1... addresses. This repository contains the CosmWasm smart contract specification and deployment documentation.

Read the full explanation: docs/HOW_IT_WORKS.md

Why SafHandle

Problem	SafHandle solution
Long, error-prone wallet addresses	Human-readable short names (john, john.saf)
Copy-paste friction in P2P payments	Resolve a name or phone to addr_safro in one query
No standard name registry on Safrochain	Canonical on-chain registry any wallet or dApp can query
Phone-based payments off-chain only	On-chain phone link now; off-chain verification in Phase 2

How it works

User registers "john.saf"  →  pays 50 SAF  →  contract stores john.saf → addr_safro1...
Anyone calls get_address  →  contract returns wallet address

sequenceDiagram
    participant User as User
    participant Wallet as Wallet
    participant Contract as SafHandle_Contract
    participant Dev as Dev_Module_Wallet

    User->>Wallet: Register john.saf
    Wallet->>Contract: register_name + 50 SAF fee
    Contract->>Dev: Transfer fee
    Contract-->>Wallet: Name registered

    participant App as dApp_or_Wallet
    App->>Contract: get_address(john)
    Contract-->>App: addr_safro1...

Loading

Fees

Action	Default fee	Routing
Register short name	50 SAF	Dev module wallet
Link phone number	100 SAF	Dev module wallet

Fees are governance-updatable. See docs/FEES_AND_GOVERNANCE.md.

Documentation

Document	Contents
docs/README.md	Documentation index
HOW_IT_WORKS.md	End-to-end user journey
ARCHITECTURE.md	On-chain design and components
CONTRACT_API.md	Execute and query message specification
NAME_RULES.md	Allowed formats and normalization
FEES_AND_GOVERNANCE.md	Fee defaults and governance params
PHONE_LINKING.md	On-chain phone links, Phase 2 verification
ANTI_SQUATTING.md	Squatting protections
STATE_SCHEMA.md	Storage layout for implementers
DEPLOYMENT.md	Deployment workflow
MIGRATION.md	Contract migration strategy
SECURITY_MODEL.md	Threat model
ROADMAP.md	Implementation phases

Planned repository layout

contracts/safhandle/
├── Cargo.toml
├── src/
│   ├── contract.rs
│   ├── msg.rs
│   ├── state.rs
│   ├── error.rs
│   ├── fees.rs
│   └── names.rs
├── tests/
└── artifacts/
    └── checksums.txt
deployment/
├── deploy.sh
├── migrate.sh
└── lib/
config/
├── testnet.json
└── mainnet.json

Network configuration

Network	Chain ID	Bech32 prefix	Denom
Mainnet	safrochain-1	addr_safro	usaf (6 decimals)
Testnet	safro-testnet-1	addr_safro	usaf (6 decimals)

See config/ for RPC endpoints and fee defaults.

Related repositories

Repository	Description
safhandle-sdk	TypeScript/JavaScript client for wallets and dApps

Contributing

See CONTRIBUTING.md. Security issues: SECURITY.md — do not open public issues for vulnerabilities.

License

MIT — Copyright (c) 2026 Safrochain