{"id":19571558,"url":"https://github.com/block-core/blockcore-dns","last_synced_at":"2025-04-27T03:32:21.927Z","repository":{"id":37906560,"uuid":"474755852","full_name":"block-core/blockcore-dns","owner":"block-core","description":"Domain Name System Server that utilizes Decentralized identifiers (DIDs) for updates","archived":false,"fork":false,"pushed_at":"2022-12-04T02:42:30.000Z","size":95,"stargazers_count":5,"open_issues_count":4,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-19T03:23:11.806Z","etag":null,"topics":["dns","dns-server","web5"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/block-core.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-03-27T20:47:34.000Z","updated_at":"2023-02-13T19:33:46.000Z","dependencies_parsed_at":"2023-01-23T23:17:52.971Z","dependency_job_id":null,"html_url":"https://github.com/block-core/blockcore-dns","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/block-core%2Fblockcore-dns","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/block-core%2Fblockcore-dns/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/block-core%2Fblockcore-dns/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/block-core%2Fblockcore-dns/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/block-core","download_url":"https://codeload.github.com/block-core/blockcore-dns/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250345183,"owners_count":21415272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["dns","dns-server","web5"],"created_at":"2024-11-11T06:19:17.128Z","updated_at":"2025-04-27T03:32:21.634Z","avatar_url":"https://github.com/block-core.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Blockcore DNS\n\nDomain Name System Server that utilizes Decentralized Identifiers (DIDs) for updates\n\n## Introduction\n\nThe help mitigate infrastructure attacks, such as shutdown of cloud-hosted services, we allow anyone to host and run our software. This will make it harder to have any efficient attacks against our networks.\n\nThe Blockcore DNS is a type of Dynamic DNS ([DDNS](https://en.wikipedia.org/wiki/Dynamic_DNS)) that allows a semi-trust or no-trust setups where anyone that runs Blockcore software can become part of the ecosystem.\n\nAnyone can run the Blockcore DNS software for their own domain, and can allow anyone or approved-list of hosters to be part of their official DNS.\n\n## DNS Server\n\nThe DNS server has several responsibilities\n\n- Resolve DNS A/AAA queries for domains that are registered to it.\n- Enable Blockcore hosted services (like the indexer) to register IP and domains (effectively becoming a Dynamic DNS).\n- Allow to query IP address/domains of Blockcore hosted services.\n- Periodically check that Blockcore hosted services are online (otherwise flag/delist them).\n\n## API\n\nThe running instance of Blockcore DNS will have a REST API that allows the running instances of Blockcore software (e.g. Blockcore Indexer, Blockcore Vault) to announce their current public IP address where consumers can access the public APIs being hosted by individual third parties.\n\n## Agent\n\nAgent mode is an instance of Blockcore DNS run by individuals hosting Blockcore software (e.g. Blockcore Indexer, Blockcore Vault), it runs side by side such software and can resolve and announce their current public IP address to Blockcore DNS servers.\n\n## How it works\n\n- Actor A will buy a domain, e.g. \"myservers.com\".\n- Actor A runs the Blockcore DNS software, preferably using Docker.\n- The Blockcore DNS will be configured by Actor A and setup with an DID (Decentralized Identfier).\n- The Blockcore DNS will automatically generate and configure an TLS certificate for secure endpoint communication. It is not a requirement to use certificates, as all messages will be signed.\n- Actor A configure their DNS instance to either be fully public (will be open for various attacks) or pre-approved list of DIDs. (fully public DNS is not supported at this stage)\n\nNext step is for Actor B to run, e.g. Blockcore Indexer or Blockcore Vault.\n\n- Actor B will buy a domain or use a subdomain (by convention we use `coin.service.domain.com` i.e `btc.indexer.blockcore.net`)\n- Actor B will configure the domain/subdomain to resolve an NS record to the Actor A server \"myservers.com\". or one of Blockcore-DNS servers (i.e `ns.blockcore.net`)\n- Actor B will install and run the Blockcore software.\n- Actor B will install and run the Blockcore DNS in agent mode.\n- Actor B will be able to configure Blockcore DNS which domains they want their hosted software to be a member of, e.g. \"myservers.com\".\n\nFinal step is consumers (users, etc.) that need to consume blockchain and other data.\n\n- Actor C will install the Blockcore Extension, which is an lightweight wallet that depends on hosted nodes.\n- Actor C will either choose \"Default\", from a list of pre-approved domains, or custom domain input for where they want to connect.\n- Actor C software will perform a normal DNS lookup and retrieve the IP of all running instances, and pick one IP to communicate with.\n\n## Getting Started\n\nUse the command `--dns-help` to show the available command line options\n\n```\ndotnet run --dns-help\n\nDomain Name System Server that utilizes Decentralized Identifiers(DIDs) for updates.\nSee the application options below.\n\noptions:\n\n--did            mode to generate a did key pair\n--agent          mode to run as client that can register domains/IPs to a dns server (ddns)\n[unspecified]    otherwise to run as a dns server mode that can serve A/AAAA records and allow agents to register domains and IPs\n```\n\n### How to create a Decentralized Identifier (DID)\n\n```\ndotnet run --did\n\nSecret key add to config 64693d03c3bf79dd1a47ba475db2ed7cd22656c117f1d9329b5bb2324585e3b2\nPublic identity did:is:03842ed7d440c0ab437f48db8bffbffdfca307253a3c38a444f4fb91297db1e45d\n```\n\nThe secret and DID will be used later in the agent and dns `appsettings.config` files\n\n### How to run an agent\n\n```\ndotnet run --agent\n```\n\nWhen running in agent mode use the secret generated from the previous step and provide the DID of that secret to any dns server that you want the agent to register it's domain data with.\n\nThe agent instance will periodically discover the current IP address, and broadcast each configured host to register it's domain with a DnsHost (DNS server)\nThe agent will build a request and sign it using schnorr signatures before sending to the server.\n\nHere is a config example of an agent configured to register a Bitcoin indexer with two dns servers \n\n```\n \"DnsAgent\": {\n    \"Hosts\": [\n      {\n        \"DnsHost\": \"http://dns1-domain.com\",\n        \"Domain\": \"btc.indexer.agent-domain.com\",\n        \"Port\": \"9910\",\n        \"Symbol\": \"BTC\",\n        \"Service\": \"Indexer\"\n      },\n      {\n        \"DnsHost\": \"http://dns2-domain.com\",\n        \"Domain\": \"btc.indexer.agent-domain.com\",\n        \"Port\": \"9910\",\n        \"Symbol\": \"BTC\",\n        \"Service\": \"Indexer\"\n      }\n    ],\n    \"IntervalMinutes\": \"5\",\n    \"DnsttlMinutes\": 20,\n    \"Secret\": \"64693d03c3bf79dd1a47ba475db2ed7cd22656c117f1d9329b5bb2324585e3b2\"\n  }\n```\n\n### How to run a DNS server\n\n```\ndotnet run\n```\n\nHere is a config exmpale of an configuration to listen to two DID \n\n```\n\"Dns\": {\n    \"ListenPort\": \"53\",\n    \"IntervalMinutes\": \"5\",\n    \"EndServerIp\": \"192.168.1.1\",\n    \"Identities\": [\n      \"did:is:03ba00574cc3821ae3d5f367696692e1b20ea25e70565e6fa6a07e7f74d266aa39\",\n      \"did:is:03842ed7d440c0ab437f48db8bffbffdfca307253a3c38a444f4fb91297db1e45d\"\n    ]\n  },\n```\n\nThe DNS server exposes the following endpoints \n\n```\nPOST /api/dns/addEntry   - add a new domain entry\nGET  /api/dns/entries    - get the list of DNS A/AAAA records\nGET  /api/dns/services   - get the list of domains registered\nGET  /api/dns/ipaddress  - return the callers ip address\n```\n\nRegistration requests that have a domain and IP address will also register an A/AAAA recored to resolve the domain to that IP address (effectively acting as a Dynamic DNS)\n\n#### Open port 53 linux\nWhen setting up a DNS server on linux its required to open port 53\nsee this guid to open that port or follow the steps bellow\nhttps://www.linuxuprising.com/2020/07/ubuntu-how-to-free-up-port-53-used-by.html\n\nOpen this file\n```\nnano /etc/systemd/resolved.conf\n```\n\nSet this params\n```\nDNS=1.1.1.1\nDNSStubListener=no\n```\n\nCreate a link\n```\nln -sf /run/systemd/resolve/resolv.conf /etc/resolv.conf\n```\n\nReboot\n\n\n## External dependencies\n\nThe DNS server uses the following nuget package to handle DNS queries\n\nhttps://github.com/kapetan/dns\n\nDocs and a usefull tool to help debug DNS queries (used by letsencrypt)\n\nhttps://unboundtest.com/\nhttps://letsencrypt.org/docs/caa/\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblock-core%2Fblockcore-dns","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblock-core%2Fblockcore-dns","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblock-core%2Fblockcore-dns/lists"}