{"id":26704003,"url":"https://github.com/mechanismhq/bns-x","last_synced_at":"2025-07-20T22:07:27.262Z","repository":{"id":90277427,"uuid":"585736574","full_name":"mechanismHQ/bns-x","owner":"mechanismHQ","description":"A protocol for extending and improving the Bitcoin Naming System","archived":false,"fork":false,"pushed_at":"2023-12-04T20:13:01.000Z","size":15902,"stargazers_count":15,"open_issues_count":3,"forks_count":10,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-03T22:42:25.290Z","etag":null,"topics":["bns","clarinet","clarity","clarity-smart-contracts","stacks"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mechanismHQ.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2023-01-05T23:59:49.000Z","updated_at":"2024-06-10T06:31:03.000Z","dependencies_parsed_at":"2023-04-12T03:05:37.873Z","dependency_job_id":"e62c8260-9c7f-434f-aed1-d63d03cda2ae","html_url":"https://github.com/mechanismHQ/bns-x","commit_stats":{"total_commits":476,"total_committers":2,"mean_commits":238.0,"dds":0.05672268907563027,"last_synced_commit":"990d12b7c1ee925b5de4aaac3c42781739272a7d"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mechanismHQ/bns-x","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mechanismHQ%2Fbns-x","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mechanismHQ%2Fbns-x/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mechanismHQ%2Fbns-x/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mechanismHQ%2Fbns-x/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mechanismHQ","download_url":"https://codeload.github.com/mechanismHQ/bns-x/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mechanismHQ%2Fbns-x/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266205631,"owners_count":23892489,"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":["bns","clarinet","clarity","clarity-smart-contracts","stacks"],"created_at":"2025-03-27T04:30:10.107Z","updated_at":"2025-07-20T22:07:27.240Z","avatar_url":"https://github.com/mechanismHQ.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BNS X\n\nBNS X is a protocol for extending and improving the Bitcoin Naming System (BNS).\n\nAt the time of writing, all aspects of the BNS X protocol are in development and unreleased.\n\nThis project is a monorepo, which includes a few packages:\n\n- Clarity contracts and tests\n  - Clarity contracts for the protocol are under [`./contracts`](./contracts/). The contracts themselves live under [`./contracts/contracts`](./contracts/contracts/). Tests are under [`./contracts/tests/`](./contracts/tests/).\n  - Auto-generated Clarity code documentation can be found under [`./docs`](./docs/).\n  - This project uses Clarinet for testing and other Clarity development purposes.\n- Web app\n  - A web app for interfacing with BNS X can be found under [`./web`](./web/)\n- API\n  - A basic API for BNS X on-chain data is under [`./api/](./api/)\n- Client\n  - A library for interacting with all things BNS is available under [`./packages/client`](./packages/client/)\n\n## Local development\n\nTo work on the project, here are a few commands needed to get setup.\n\n**Install dependencies**\n\nFor this project, you'll need `pnpm`, `clarinet`, [`clarigen`](https://clarigen.dev), and [`velociraptor`](https://velociraptor.run).\n\nOnce they're installed, run `pnpm install` to install package dependencies.\n\n**Running contract tests**\n\nAll contracts and tests are under the `contracts` folder. To run tests:\n\n```ts\ncd contracts\nclarinet test\n```\n\n### Running a local environment (blockchain, API, and web app)\n\n**Speedrun version**\n\n1. `vr integrate` - start the Clarinet devnet\n   - Leave running and open a new CLI tab\n1. `vr boostrap`\n   - Leave running and open a new CLI tab\n1. `pnpm build:packages`\n1. `pnpm dev:api`\n   - Leave running and open a new CLI tab\n1. `pnpm dev:web`\n   - Visit Dots at [localhost:3000](http://localhost:3000)\n\n#### Setup and start a Devnet chain\n\nTo start up the local devnet environment:\n\n```bash\nvr integrate\n```\n\nThis will run some setup scripts and then run `clarinet integrate`.\n\nOnce the chain is running and BNS contracts are deployed, run:\n\n```bash\nvr bootstrap\n```\n\nThis will run a script that polls the local devnet chain and deploys a few setup contracts once the chain is setup.\n\n#### Build local packages\n\nThe API and web app use local packages inside this monorepo, so they must be built. To do so, run:\n\n```bash\npnpm build:packages\n```\n\n#### Setup and run the API\n\nNext, run:\n\n```bash\npnpm dev: api\n```\n\nThis will start the API at [localhost:3002](http://localhost:3002)\n\n**Optional: setup Postgres in the API server**\n\nBy default, the API runs in a \"fallback\" mode that queries on-chain contracts for all API requests. This works, but is less efficient and doesn't include all API endpoints.\n\nTo setup Postgres, make sure Postgres is installed and running on your machine. Next, create a file at `./api/.env` with:\n\n```\n# local postgres DB, you can change the DB name:\nBNSX_DB_URL=\"postgresql://localhost:5432/bnsx-dev?schema=public\"\n```\n\nYou might need to change the username and password for this to work, depending on your local Postgres environment.\n\nNext, create another file at `./api/.env.local` with:\n\n```\n# Stacks API DB: don't change this, it comes from clarinet integrate's docker setup\nSTACKS_API_POSTGRES=\"postgresql://postgres:postgres@localhost:5433/stacks_api\"\n\n# keep this to ensure your local API stays in sync:\nWORKER=true\n```\n\nNext, run (in the `api` folder):\n\n```bash\npnpm prisma migrate dev\n```\n\nWhen you restart your local devnet environment, you'll need to run `pnpm prisma migrate reset` to wipe your DB.\n\nThen, run the API with `pnpm dev`.\n\n#### Setup and run the web app\n\nYou can now run the web app with:\n\n```\npnpm dev:web\n```\n\n### Running Dots on mainnet\n\nTo run the Dots app for mainnet, modify `web/.env.local` to include:\n\n```\nNEXT_PUBLIC_NETWORK_KEY=mainnet\nNEXT_PUBLIC_API_URL=https://api.bns.xyz\n```\n\nOnce changes, run `pnpm dev` in the `web` folder to run a mainnet version of Dots.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmechanismhq%2Fbns-x","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmechanismhq%2Fbns-x","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmechanismhq%2Fbns-x/lists"}