{"id":20245052,"url":"https://github.com/interlay/interbtc-api","last_synced_at":"2025-04-06T10:09:53.837Z","repository":{"id":36958161,"uuid":"293627189","full_name":"interlay/interbtc-api","owner":"interlay","description":"interBTC TypeScript SDK","archived":false,"fork":false,"pushed_at":"2024-11-25T10:26:59.000Z","size":7066,"stargazers_count":26,"open_issues_count":30,"forks_count":20,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-27T09:49:19.322Z","etag":null,"topics":["bitcoin","interbtc","polkadot","typescript"],"latest_commit_sha":null,"homepage":"https://app.interlay.io/","language":"TypeScript","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/interlay.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-09-07T20:34:43.000Z","updated_at":"2024-10-07T08:53:43.000Z","dependencies_parsed_at":"2024-10-04T10:55:26.045Z","dependency_job_id":"53ac441b-89d2-4d39-a91d-26a6d39dc21a","html_url":"https://github.com/interlay/interbtc-api","commit_stats":{"total_commits":1521,"total_committers":22,"mean_commits":69.13636363636364,"dds":0.7041420118343196,"last_synced_commit":"1c0379f56248ac2da57930d5704199f69f941aa8"},"previous_names":["interlay/polkabtc-js"],"tags_count":285,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interlay%2Finterbtc-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interlay%2Finterbtc-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interlay%2Finterbtc-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interlay%2Finterbtc-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/interlay","download_url":"https://codeload.github.com/interlay/interbtc-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247464186,"owners_count":20942966,"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":["bitcoin","interbtc","polkadot","typescript"],"created_at":"2024-11-14T09:18:42.963Z","updated_at":"2025-04-06T10:09:53.809Z","avatar_url":"https://github.com/interlay.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# interbtc-api\n\n## About\n\nThe interBTC TypeScript library connects the Polkadot and Kusama ecosystems with Bitcoin. It allows the creation of iBTC on Polkadot and kBTC on Kusama, fungible \"wrapped\" tokens that represent Bitcoin. Wrapped tokens are backed by Bitcoin 1:1 and allow redeeming of the equivalent amount of Bitcoins by relying on a collateralized third-party (Vaults).\nIn comparison to other bridge constructions (like tBTC, wBTC, or RenVM) _anyone_ can become an intermediary by depositing collateral making interBTC the only truly open system.\n\nThe bridge itself follows the detailed specification: \u003ca href=\"https://spec.interlay.io/\" target=\"_blank\"\u003e\u003cstrong\u003eExplore the specification »\u003c/strong\u003e\u003c/a\u003e\n\nIt is implemented as a collection of open-source Substrate modules using Rust: \u003ca href=\"https://github.com/interlay/interbtc\" target=\"_blank\"\u003e\u003cstrong\u003eExplore the implementation »\u003c/strong\u003e\u003c/a\u003e\n\n### Built with\n\n- [TypeScript](https://github.com/Microsoft/TypeScript)\n- [polkadot-js](https://polkadot.js.org/)\n- [nvm](https://github.com/nvm-sh/nvm)\n- [yarn](https://github.com/yarnpkg/yarn)\n- [docker-compose](https://docs.docker.com/compose/)\n\nYou can visit [bridge.interlay.io](https://bridge.interlay.io/) to see the library in action.\n\n## Usage\n\nThe library assumes you have a version of the [Interlay or Kintsugi networks](https://github.com/interlay/interbtc) running locally or remotely.\n\n### Creating an API Instance\n\nTo use the library, you will first need to create a PolkadotJS `APIPromise` instance,\nand then instantiate a `InterBtcApi` instance.\n\n```ts\nimport { createInterBtcApi } from \"@interlay/interbtc\";\n\n// If you are using a local development environment\n// const PARACHAIN_ENDPOINT = \"ws://127.0.0.1:9944\";\n// if you want to use the Interlay-hosted beta network\nconst PARACHAIN_ENDPOINT = \"wss://api.interlay.io/parachain\";\nconst bitcoinNetwork = \"mainnet\";\nconst interBTC = await createInterBtcApi(PARACHAIN_ENDPOINT, bitcoinNetwork);\n\n// When finished using the API, disconnect to allow Node scripts to gracefully terminate\ninterBTC.disconnect();\n```\n\n### Attaching an Account\n\nTo emit transactions, an `account` has to be set.\nThe account should conform to the `AddressOrPair` interface.\nIf the account is not of the `KeyringPair` type, then a signer must also\nbe provided (such as an injected extension signer, from the Polkadot wallet).\nSee more details here: https://polkadot.js.org/docs/extension/usage/\n\n```ts\nimport { createTestKeyring } from \"@polkadot/keyring/testing\";\nconst keyring = createTestKeyring();\nconst keypair = keyring.getPairs()[0];\ninterBTC.setAccount(keypair);\n```\n\nThe different functionalities are then exposed through the `InterBtcApi` instance.\n\n### Issuing\n\nFrom the account you set, you can then request to issue (mint) interBTC.\n\n```ts\nimport { BitcoinAmount } from \"@interlay/monetary-js\";\n// amount of BTC to convert to interBTC\n// NOTE: the bridge fees will be deducted from this. For example, if you request 1 BTC, you will receive about 0.995 interBTC\nconst amount = BitcoinAmount.from.BTC(0.001);\n// request to issue interBTC\nconst requestResults = await interBTC.issue.request(amount);\n// the request results includes the BTC address(es) and the BTC that should be sent to the Vault(s)\n// NOTE: the library will automatically distribute issue requests across multiple Vaults if no single Vault can fulfill the request.\n// Most of the time, a single Vault will be able to fulfill the request.\n```\n\nSend BTC using the wallet of your choice or the regtest node (see below).\n\n### Redeeming\n\nTo exchange interBTC back for physical BTC, you can then request to redeem (burn) interBTC.\n\n```ts\nimport { BitcoinAmount } from \"@interlay/monetary-js\";\n// the amount wrapped tokens to redeem\n// NOTE: the bridge fees will be deducted from this \nconst amount = BitcoinAmount.from.BTC(0.001);\n// your BTC address\nconst btcAddress = \"tb123....\";\n// the request results includes the BTC address(es) and the BTC that should be sent to the Vault(s)\n// NOTE: the library will automatically distribute redeem requests across multiple Vaults if no single Vault can fulfill the request.\n// Most of the time, a single Vault will be able to fulfill the request.\nconst requestResults = await interBTC.redeem.request(amount, btcAddress);\n```\n\nOne or more Vaults will send BTC to the address specified within the expiry period.\n\n### Creating an AccountId Instance\n\nCertain API calls require a parameter of type `AccountId`, which represents the Polkadot/Kusama account and can be instantiated as follows\n\n```ts\nconst accountId = await interBTC.api.createType(\n    \"AccountId\",\n    \"5Ck5SLSHYac6WFt5UZRSsdJjwmpSZq85fd5TRNAdZQVzEAPT\"\n);\n```\n\n### More examples\n\nThere are many examples in the integration tests, showing how to use this library. Take a look at them here: https://github.com/interlay/interbtc-api/tree/master/test/integration\n\n## Development\n\n### Fork this repository\n\nFollow Github's instructions on [how to fork a repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo) to create your own fork.\n\n### Clone your repository\n\n```bash\ngit@github.com:\u003cyour_github_profile\u003e/interbtc-api.git\ncd interbtc-api\n```\n\n### Setting up a local development environment\n\nStart by setting your Node version via `nvm`\n\n```bash\nnvm use\n```\n\n(If necessary, `nvm` will guide you on how to install the version.)\n\nNext, install the dependencies\n\n```bash\nyarn install\n```\n\nFinally, build the library\n\n```bash\nyarn build\n```\n\n### Testing\n\nTo run unit tests only, use\n\n```bash\nyarn test:unit\n```\n\n#### Start the parachain locally for integration tests\n\nNote that the parachain needs to be running for all tests to run.\n\n```bash\ndocker-compose up -d\n```\n\nThe default parachain runtime is Kintsugi.\n\n#### Run all tests\n\nThen, to run all tests:\n\n```bash\nyarn test\n```\n\n#### Run integration tests only\n\n```bash\nyarn test:integration\n```\n\nNOTE: While the parachain is starting up, there will be warnings from the integration tests until it can locate the locally running test vaults. Expect the startup to take a few seconds, before the integration tests start.\n\n##### Dealing with timeouts during local testing\n\nAt times, when running tests locally, the timeout set in `package.json`'s `jest.testTimeout` setting might not be enough. In that case, you can override the `testTimeout` value (in ms) on the command line:\n\n```bash\nyarn test:integration --testTimeout=900000\n```\n\n##### Check service logs in detached mode\nTo check the logs or the services (for example, `vault_1`) you can use this:\n\n```bash\ndocker-compose logs -f vault_1\n```\n\nNOTE: The optional `-f` flag attaches the terminal to the log output, you will need to \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e to exit. Alternatively, omit the flag to just get the current latest log entries.\n\n#### Stop the local parachain\n\nTo stop the locally running parachain, run:\n\n```bash\ndocker-compose down -v\n```\n\nNOTE: This will remove the volumes attached to the images. So your chain will start next time in a clean/wiped state. \n\n### Updating types\n\nWe only need to update types when we have changed to newer docker images for the parachain / clients.\n\nRun the parachain (as shown above) and update the metadata:\n\n```bash\nyarn update-metadata\n```\n\nThen, update the metadata by building the library:\n\n```bash\nyarn build\n```\n\n### Usage as script\n\nThis repository contains a number of scripts for various use cases. Check `package.json` for all of the available scripts. \n\n**Query Undercollateralized borrowers**\n\nGiven a `PARACHAIN_ENDPOINT` (e.g. `wss://api-dev-kintsugi.interlay.io/parachain`), the following will print a table with all undercollateralized borrowers on that network.\n```bash\nyarn install\nyarn undercollateralized-borrowers --parachain-endpoint PARACHAIN_ENDPOINT\n```\n\n## Help\n\n### Bitcoin Regtest\n\nRegtest is a local Bitcoin instance that allows you to practically anything including sending transactions, mining blocks, and generating new addresses.\nFor a full overview, [head over to the Bitcoin developer documentation](https://developer.bitcoin.org/examples/testing.html#regtest-mode).\n\n**Sending Transactions**\n\nFor the issue process, you need to send a transaction. On regtest this can be achieved with:\n\n```shell\nbitcoin-cli -regtest -rpcwallet=Alice sendtoaddress VAULT_ADDRESS AMOUNT\n```\n\n**Mining Blocks**\n\nIn regtest, blocks are not automatically produced. After you sent a transaction, you need to mine e.g., 1 block:\n\n```shell\nbitcoin-cli -regtest generatetoaddress 1 $(bitcoin-cli -regtest getnewaddress)\n```\n\n**Getting Balances**\n\nYou can query the balance of your wallet like so:\n\n```shell\nbitcoin-cli -regtest -rpcwallet=Alice getbalance\n```\n\n### Docker\n\nYou can hard-reset the docker dependency setup with the following commands:\n\n```shell\ndocker kill $(docker ps -q)\ndocker rm $(docker ps -a -q)\ndocker rmi $(docker images -q)\ndocker volume rm $(docker volume ls -q)\n```\n\n## Contributing\n\nContributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.\n\n1. Set up git so you can [sign your commits](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work) (Alternative link: [GitHub: Signing commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits))  \nUnsigned PRs cannot be merged, so do not skip this step.\n2. Fork the Project\n3. Create your Feature Branch (git checkout -b yourname/AmazingFeature)\n4. Commit your Changes (git commit -m 'Add some AmazingFeature')\n5. Push to the Branch (git push origin yourname/AmazingFeature)\n6. Open a Pull Request with a description of feature you are adding\n\nIf you are searching for a place to start or would like to discuss features, reach out to us:\n\n- [Discord](https://discord.com/invite/interlay)\n\n## License\n\n(C) Copyright 2022 [Interlay](https://www.interlay.io) Ltd\n\ninterbtc-js is licensed under the terms of the Apache License (Version 2.0). See [LICENSE](LICENSE).\n\n## Contact\n\nWebsite: [Interlay.io](https://www.interlay.io)\n\nTwitter: [@interlayHQ](https://twitter.com/InterlayHQ)\n\nEmail: contact@interlay.io\n\n## Acknowledgements\n\nWe would like to thank the following teams for their continuous support:\n\n-   [Web3 Foundation](https://web3.foundation/)\n-   [Parity Technologies](https://www.parity.io/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finterlay%2Finterbtc-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finterlay%2Finterbtc-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finterlay%2Finterbtc-api/lists"}