{"id":48126282,"url":"https://github.com/frol/near-dns","last_synced_at":"2026-04-04T16:27:13.397Z","repository":{"id":332936981,"uuid":"1135305612","full_name":"frol/near-dns","owner":"frol","description":"Demo of how NEAR can be used as a storage layer for decentralized DNS records","archived":false,"fork":false,"pushed_at":"2026-01-16T16:22:20.000Z","size":78,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-17T00:40:04.466Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://neardns.near","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/frol.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-15T23:13:08.000Z","updated_at":"2026-01-16T21:16:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/frol/near-dns","commit_stats":null,"previous_names":["frol/near-dns"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/frol/near-dns","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frol%2Fnear-dns","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frol%2Fnear-dns/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frol%2Fnear-dns/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frol%2Fnear-dns/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/frol","download_url":"https://codeload.github.com/frol/near-dns/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frol%2Fnear-dns/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31405701,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-04T16:27:12.673Z","updated_at":"2026-04-04T16:27:13.382Z","avatar_url":"https://github.com/frol.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NEAR DNS\n\nA decentralized DNS system that resolves blockchain-based domain names by querying smart contracts on NEAR Protocol.\n\n## Overview\n\nNEAR DNS enables domain name resolution for NEAR ecosystem TLDs (`.near`, `.testnet`, etc.) by storing DNS records in smart contracts. Each NEAR account can deploy a DNS contract as a subaccount (`dns.\u003caccount\u003e.\u003ctld\u003e`) to manage their domain's DNS records.\n\n**Key Design Principle**: NEAR DNS is not intended to be a centralized DNS provider. Since all DNS records are stored on the NEAR blockchain, the DNS server itself is essentially a stateless gateway that translates DNS queries into blockchain lookups. **Self-hosting is encouraged** — you can run your own instance and get the exact same results as any other instance, because the source of truth is always the blockchain.\n\n### How It Works\n\n1. **DNS Query**: Client queries `example.near` A record\n2. **TLD Detection**: Server identifies `.near` as a NEAR TLD\n3. **Contract Lookup**: Server queries `dns.example.near` contract for records\n4. **Response**: DNS records are returned from the blockchain\n\nFor traditional domains (`.com`, `.org`, etc.), queries are forwarded to upstream DNS servers (Google/Cloudflare).\n\n## Architecture\n\n```\n┌─────────────┐     ┌──────────────────┐     ┌─────────────────┐\n│  DNS Client │────▶│  NEAR DNS Server │────▶│  NEAR Blockchain│\n│   (dig)     │◀────│   (Rust/Hickory) │◀────│  (DNS Contract) │\n└─────────────┘     └──────────────────┘     └─────────────────┘\n                            │\n                            ▼\n                    ┌───────────────┐\n                    │ Upstream DNS  │\n                    │ (Google/CF)   │\n                    └───────────────┘\n```\n\n## Learn More\n\n* For developers with or without web3 background: [NEAR DNS - DNS records stored on blockchain and served over DNS protocol](https://www.reddit.com/r/rust/comments/1qew4ra/near_dns_dns_records_stored_on_blockchain_and/)\n* For developers with web3 background: [NEAR DNS - DNS records stored on NEAR and served over DNS protocol](https://www.reddit.com/r/nearprotocol/comments/1qek7qz/near_dns_dns_records_stored_on_near_and_servered/)\n\n## Public DNS Server\n\nThere is currently one publicly available NEAR DNS server connected to **mainnet**:\n\n```\nDNS Server: 185.149.40.161 (port 53)\n```\n\nTry it out:\n\n```bash\n# Query a mainnet domain\ndig @185.149.40.161 neardns.near A\n\n# Expected response:\n# neardns.near.    1    IN    A    185.149.40.161\n```\n\n\u003e **Note**: This public server is provided for convenience, but self-hosting is encouraged. Since NEAR DNS is stateless (all data comes from the blockchain), running your own instance gives you the same results with better privacy and no single point of failure.\n\n## Components\n\n### DNS Server (`dns-server/`)\n\nA Rust DNS server built with [Hickory DNS](https://github.com/hickory-dns/hickory-dns) that:\n\n- Resolves NEAR domains by querying smart contracts via RPC\n- Forwards non-NEAR domains to upstream DNS servers\n- Supports hierarchical subdomain resolution\n- Implements wildcard record matching\n- Caches responses for performance\n\n### DNS Contract (`dns-contract/`)\n\nA NEAR smart contract that stores DNS records with:\n\n- Support for common record types (A, AAAA, CNAME, MX, TXT, etc.)\n- Owner-only record management (parent account controls records)\n- Wildcard record support (`*` entries)\n- Iterable storage for listing all records\n\n## Quick Start\n\n### Prerequisites\n\n- Rust 1.86\n- [NEAR CLI](https://near.cli.rs)\n- A NEAR account (testnet or mainnet)\n\n### Running the DNS Server\n\n#### For Mainnet\n\n```bash\n# Clone and build\ngit clone https://github.com/frol/near-dns\ncd near-dns\ncargo build --release --package near-dns-server\n\n# Run the server (mainnet)\nRUST_LOG=info ./target/release/near-dns-server \\\n  --bind 127.0.0.1:5355 \\\n  --rpc-url https://rpc.mainnet.near.org\n\n# Test with dig\ndig @127.0.0.1 -p 5355 neardns.near A\n```\n\n#### For Testnet\n\n```bash\n# Run the server (testnet)\nRUST_LOG=info ./target/release/near-dns-server \\\n  --bind 127.0.0.1:5355 \\\n  --rpc-url https://rpc.testnet.near.org\n\n# Test with dig\ndig @127.0.0.1 -p 5355 near-dns.testnet A\ndig @127.0.0.1 -p 5355 near-dns.testnet TXT\n```\n\nNon-NEAR domains are forwarded to upstream DNS servers:\n\n```bash\ndig @127.0.0.1 -p 5355 google.com A  # Forwarded upstream\n```\n\n### Running with Docker\n\n#### Mainnet (Default)\n\n```bash\n# Run with mainnet RPC (default)\ndocker run -d --name near-dns \\\n  -p 53:53/udp \\\n  -p 53:53/tcp \\\n  frolvlad/near-dns\n\n# Test it\ndig @localhost neardns.near A\n```\n\n#### Testnet\n\n```bash\n# Run with testnet RPC\ndocker run -d --name near-dns-testnet \\\n  -p 5355:53/udp \\\n  -p 5355:53/tcp \\\n  frolvlad/near-dns \\\n  --bind 0.0.0.0:53 \\\n  --rpc-url https://rpc.testnet.near.org\n\n# Test it\ndig @localhost -p 5355 near-dns.testnet A\n```\n\n#### Additional Options\n\n```bash\n# Run with custom log level\ndocker run -d --name near-dns \\\n  -e RUST_LOG=debug \\\n  -p 53:53/udp \\\n  -p 53:53/tcp \\\n  frolvlad/near-dns\n\n# View logs\ndocker logs -f near-dns\n```\n\n#### Building from Source\n\n```bash\ndocker build -t near-dns .\ndocker run -d -p 5355:53/udp -p 5355:53/tcp near-dns\n```\n\n### Register Your Own Domain (aka Deploying Your Own DNS Contract)\n\nBuild the contract first using [`cargo near`](https://github.com/near/cargo-near):\n\n```bash\ncd dns-contract\ncargo near build\n```\n\n#### Mainnet\n\n```bash\n# Create a subaccount for DNS\nnear account create-account fund-myself dns.youraccount.near '2.1 NEAR' \\\n  autogenerate-new-keypair save-to-keychain \\\n  sign-as youraccount.near network-config mainnet sign-with-keychain send\n\n# Build the contract\ncd dns-contract\ncargo near build non-reproducible-wasm\n\n# Deploy with initialization\nnear contract deploy dns.youraccount.near \\\n  use-file target/near/dns_contract.wasm \\\n  with-init-call new json-args '{}' \\\n  prepaid-gas '30 Tgas' attached-deposit '0 NEAR' \\\n  network-config mainnet sign-with-keychain send\n```\n\n#### Testnet\n\nUnlike mainnet, you can create a new account and get some free NEAR tokens on testnet using this simple command:\n\n```bash\nnear account create-account sponsor-by-faucet-service\n```\n\n```bash\n# Create a subaccount for DNS\nnear account create-account fund-myself dns.youraccount.testnet '2.1 NEAR' \\\n  autogenerate-new-keypair save-to-keychain \\\n  sign-as youraccount.testnet network-config testnet sign-with-keychain send\n\n# Deploy with initialization\nnear contract deploy dns.youraccount.testnet \\\n  use-file target/near/dns_contract.wasm \\\n  with-init-call new json-args '{}' \\\n  prepaid-gas '30 Tgas' attached-deposit '0 NEAR' \\\n  network-config testnet sign-with-keychain send\n```\n\n### Managing DNS Records\n\nThe examples below use testnet. For mainnet, replace `.testnet` with `.near` and `network-config testnet` with `network-config mainnet`.\n\n```bash\n# Add an A record\nnear contract call-function as-transaction dns.youraccount.testnet dns_add \\\n  json-args '{\"name\": \"@\", \"record\": {\"record_type\": \"A\", \"value\": \"1.2.3.4\", \"ttl\": 300, \"priority\": null}}' \\\n  prepaid-gas '30 Tgas' attached-deposit '0 NEAR' \\\n  sign-as youraccount.testnet network-config testnet sign-with-keychain send\n\n# Add a subdomain\nnear contract call-function as-transaction dns.youraccount.testnet dns_add \\\n  json-args '{\"name\": \"www\", \"record\": {\"record_type\": \"A\", \"value\": \"1.2.3.5\", \"ttl\": 300, \"priority\": null}}' \\\n  prepaid-gas '30 Tgas' attached-deposit '0 NEAR' \\\n  sign-as youraccount.testnet network-config testnet sign-with-keychain send\n\n# Add a wildcard record (matches any subdomain)\nnear contract call-function as-transaction dns.youraccount.testnet dns_add \\\n  json-args '{\"name\": \"*\", \"record\": {\"record_type\": \"A\", \"value\": \"1.2.3.100\", \"ttl\": 300, \"priority\": null}}' \\\n  prepaid-gas '30 Tgas' attached-deposit '0 NEAR' \\\n  sign-as youraccount.testnet network-config testnet sign-with-keychain send\n\n# Query records\nnear contract call-function as-read-only dns.youraccount.testnet dns_query \\\n  json-args '{\"name\": \"@\", \"record_type\": \"A\"}' \\\n  network-config testnet now\n\n# List all records\nnear contract call-function as-read-only dns.youraccount.testnet dns_list_all \\\n  json-args '{}' network-config testnet now\n```\n\n## Contract API\n\n### View Methods\n\n| Method | Arguments | Description |\n|--------|-----------|-------------|\n| `dns_query` | `name: String, record_type: String` | Query specific record type for a name |\n| `dns_query_all` | `name: String` | Get all record types for a name |\n| `dns_list_names` | - | List all DNS names with records |\n| `dns_list_all` | - | List all records in the contract |\n| `get_owner` | - | Get the contract owner |\n\n### Change Methods\n\n| Method | Arguments | Description |\n|--------|-----------|-------------|\n| `dns_add` | `name: String, record: DnsRecord` | Add a DNS record |\n| `dns_update` | `name: String, records: Vec\u003cDnsRecord\u003e` | Replace all records of a type |\n| `dns_delete` | `name: String, record_type: Option\u003cString\u003e` | Delete records |\n| `transfer_ownership` | `new_owner: AccountId` | Transfer contract ownership |\n\n### DnsRecord Structure\n\n```json\n{\n  \"record_type\": \"A\",\n  \"value\": \"192.168.1.1\",\n  \"ttl\": 300,\n  \"priority\": null\n}\n```\n\nSupported record types: `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `NS`, `SRV`, `SOA`, `PTR`, `CAA`\n\n## Resolution Logic\n\nFor a query like `sub.example.near`:\n\n1. Check if `near` is a known NEAR TLD\n2. Try `dns.sub.example.near` with name `@`\n3. Try `dns.example.near` with name `sub`\n4. Try `dns.example.near` with name `*` (wildcard)\n5. Return NXDOMAIN if no records found\n\n## Supported TLDs\n\nThe DNS server recognizes these NEAR TLDs:\n- `near` (mainnet)\n- `testnet`\n- `aurora`\n- `tg`\n- `sweat`\n- `kaiching`\n- `sharddog`\n\nAll other TLDs are forwarded to upstream DNS servers.\n\n## Deployed Contracts\n\n### Mainnet\n\n- **Contract**: `dns.neardns.near`\n- **Owner**: `neardns.near`\n\n### Testnet\n\n- **Contract**: `dns.near-dns.testnet`\n- **Owner**: `near-dns.testnet`\n\n## Development\n\n```bash\n# Run DNS server tests\ncd dns-server\ncargo test\n\n# Run contract tests\ncd dns-contract\ncargo test\n\n# Build contract WASM\ncd dns-contract\ncargo near build non-reproducible-wasm\n```\n\n## License\n\nLicensed under either of:\n\n- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)\n- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)\n\nat your option.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrol%2Fnear-dns","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffrol%2Fnear-dns","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrol%2Fnear-dns/lists"}