{"id":17939405,"url":"https://github.com/libitx/txbox","last_synced_at":"2025-03-24T10:32:08.911Z","repository":{"id":57556415,"uuid":"269140698","full_name":"libitx/txbox","owner":"libitx","description":"Elixir Bitcoin transaction storage schema, built on Ecto.","archived":false,"fork":false,"pushed_at":"2022-08-25T12:06:32.000Z","size":355,"stargazers_count":17,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-19T03:39:42.430Z","etag":null,"topics":["bitcoin","bsv","ecto","elixir","schema"],"latest_commit_sha":null,"homepage":"https://hexdocs.pm/txbox","language":"Elixir","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/libitx.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":"2020-06-03T16:36:02.000Z","updated_at":"2024-05-01T09:06:48.000Z","dependencies_parsed_at":"2022-09-14T12:22:21.280Z","dependency_job_id":null,"html_url":"https://github.com/libitx/txbox","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libitx%2Ftxbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libitx%2Ftxbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libitx%2Ftxbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libitx%2Ftxbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/libitx","download_url":"https://codeload.github.com/libitx/txbox/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245252426,"owners_count":20585060,"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","bsv","ecto","elixir","schema"],"created_at":"2024-10-29T00:07:10.777Z","updated_at":"2025-03-24T10:32:08.558Z","avatar_url":"https://github.com/libitx.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Txbox\n\n![Elixir Bitcoin Tx storage schema](https://github.com/libitx/txbox/raw/master/media/poster.png)\n\n![Hex.pm](https://img.shields.io/hexpm/v/txbox?color=informational)\n![License](https://img.shields.io/github/license/libitx/txbox?color=informational)\n![Build Status](https://img.shields.io/github/workflow/status/libitx/txbox/Elixir%20CI)\n\nTxbox is a Bitcoin transaction storage schema. It lets you store Bitcoin transactions in your application's database with searchable and filterable semantic metadata. Txbox is inspired by [TXT](https://txt.network/) but adapted to slot into an Elixir developers toolset.\n\n* Built on Ecto! Store Bitcoin Transactions in your database and define associations with any other data from your app's domain.\n* Built in queue for pushing signed transactions to the Bitcoin network via the [Miner API](https://github.com/bitcoin-sv/merchantapi-reference).\n* Auto-syncs with the [Miner API](https://github.com/bitcoin-sv/merchantapi-reference) of your choice, and caches signed responses.\n* Aims to be compatible with TXT, with similar schema design and API for searching and filtering.\n* Unlike TXT, no web UI or HTTP API is exposed. Txbox is purely a database schema with query functions - the rest is up to you.\n* Coming soon (™) - Seamlessly import and export from other TXT-compatible platforms.\n\n## Installation\n\nThe package can be installed by adding `txbox` to your list of dependencies in `mix.exs`.\n\n\n```elixir\ndef deps do\n  [\n    {:txbox, \"~\u003e 0.3\"}\n  ]\nend\n```\n\nOnce installed, update your application's configuration, making sure Txbox knows which Repo to use.\n\n```elixir\n# config/config.exs\nconfig :txbox, repo: MyApp.Repo\n```      \n\nNext, `Txbox` to your application's supervision tree.\n\n```elixir\nchildren = [\n  {Txbox, [\n    # Manic miner configuration (defaults to :taal)\n    miner: {:taal, headers: [{\"token\", \"MYTOKEN\"}]},\n    # Maximum number of times to attempt polling the miner (default is 20)\n    max_status_attempts: 20,\n    # Interval (in seconds) between each mAPI request (default is 300 - 5 minutes)\n    retry_status_after: 300\n  ]}\n]\n\nSupervisor.start_link(children, strategy: :one_for_one)\n```\n\nFinally, run the following tasks to generate and run the required database migrations.\n\n```console\nmix txbox.gen.migrations\nmix ecto.migrate\n```\n\n## Upgrading\n\nIf upgrading from a previous version of `txbox`, make sure to run the migrations\ntask to check if any new migrations are required.\n\n```console\nmix txbox.gen.migrations\n# If needed\nmix ecto.migrate\n```\n\n## Usage\n\nFor detailed examples, refer to the [full documentation](https://hexdocs.pm/txbox).\n\nOnce up an running, using Txbox is simple. The `Txbox` modules provides four CRUD-like functions for managing transactions: `create/2`, `update/2`, `find/2` and `all/2`.\n\nTo add a transaction to Txbox, the minimum required is to give a `txid`.\n\n```elixir\nTxbox.create(%{\n  txid: \"6dfccf46359e033053ab1975c1e008ddc98560f591e8ed1c8bd051050992c110\"\n})\n```\n\nOnce a transaction is added, Txbox automatically syncs with the Miner API of your choice, updating the transaction's status until it is confirmed in a block.\n\nWhen a channel name is ommitted, transactions are added to the `default_channel/0` (`\"txbox\"`), but by specifiying a channel name as the first argument, the transaction will be added to that channel. You can provide additional metadata about the transaction, as well as attach the raw transaction binary.\n\n```elixir\nTxbox.create(\"photos\", %{\n  txid: \"6dfccf46359e033053ab1975c1e008ddc98560f591e8ed1c8bd051050992c110\",\n  rawtx: \u003c\u003c...\u003e\u003e,\n  tags: [\"hubble\", \"universe\"],\n  meta: %{\n    title: \"Hubble Ultra-Deep Field\"\n  },\n  data: %{\n    bitfs: \"https://x.bitfs.network/6dfccf46359e033053ab1975c1e008ddc98560f591e8ed1c8bd051050992c110.out.0.3\"\n  }\n})\n```\n\nThe transaction can be retrieved by the `txid`.\n\n```elixir\nTxbox.find(\"6dfccf46359e033053ab1975c1e008ddc98560f591e8ed1c8bd051050992c110\")\n```\n\nAs before, omitting the channel scopes the query to the `default_channel/0` (`\"txbox\"`). Alterntively you can pass the channel name as the first argument, or use `\"_\"` which is the TXT syntax for global scope.\n\n```elixir\nTxbox.find(\"_\", \"6dfccf46359e033053ab1975c1e008ddc98560f591e8ed1c8bd051050992c110\")\n```\n\nA list of transactions can be returned using `all/2`. The second parameter must be a `t:map/0` of query parameters to filter and search by.\n\n```elixir\nTxbox.all(\"photos\", %{\n  from: 636400,\n  tagged: \"hubble\",\n  limit: 5\n})\n```\n\nA full text search can be made by using the `:search` filter parameter.\n\n```elixir\nTxbox.all(\"_\", %{\n  search: \"hubble deep field\"\n})\n```\n\n### Filtering and searching\n\nTxbox adopts the same syntax and query modifiers [used by TXT](https://txt.network/#/?id=c-queries). Txbox automatically normalizes the query map, so keys can be specifiied either as atoms or strings. Here are a few examples:\n\n* `:search` - Full text search made on trasactions' tags and meta data\n  * `%{search: \"hubble deep field\"}`\n* `:tagged` - Filter transactions by the given tag or tags\n  * `%{tagged: \"photos\"}` - all transactions tagged with \"photos\"\n  * `%{tagged: [\"space\", \"hubble\"]}` - all transactions tagged with *both* \"space\" and \"hubble\"\n  * `%{tagged: \"space, hubble\"}` - as above, but given as a comma seperated string\n* `:from` - The block height from which to filter transactions by\n  * `%{from: 636400}` - all transactions from and including block 636400\n* `:to` - The block height to which to filter transactions by\n  * `%{to: 636800}` - all transactions upto and including block 636800\n  * `%{from: 636400, to: 636800}` - all transactions in the range 636400 to 636800\n* `:at` - The block height at which to filter transactions by exactly\n  * `%{at: 636500}` - all transactions at block 636500\n  * `%{at: \"null\"}` - all transactions without a block height (unconfirmed)\n  * `%{at: \"!null\"}` - all transactions with any block height (confirmed)\n* `:order` - The attribute to sort transactions by\n  * `%{order: \"i\"}` - sort by block height in ascending order\n  * `%{order: \"-i\"}` - sort by block height in descending order\n  * `%{order: \"created_at\"}` - sort by insertion time in ascending order\n  * `%{order: \"-created_at\"}` - sort by insertion time in descending order\n* `:limit` - The maximum number of transactions to return\n* `:offset` - The start offset from which to return transactions (for pagination)\n\n\n## Transaction state machine and miner API integration\n\nUnder the hood, Txbox is packed with a powerful state machine with automatic miner API integration.\n\n![Txbox state machine](https://github.com/libitx/txbox/raw/master/media/state-machine.png)\n\nWhen creating a new transaction, you can set its state to one of the following values.\n\n* `\"pending\"` - If no state is specified, the default state is `\"pending\"`. Pending transactions can be considered draft or incomplete transactions. Draft transactions can be updated, and will not be pushed to miners unless the state changes.\n* `\"queued\"` - Under the `\"queued\"` state, a transaction will be asynchronously pushed to the configured miner API in the background. Depending on the miner response, the state will transition to `\"pushed\"` or `\"failed\"`.\n* `\"pushed\"` - If the state is specified as `\"pushed\"`, this tells Txbox the transaction is already accepted by miners. In the background, Txbox will poll the configured miner API until a response confirms the transaction is in a block.\n\nThe miner API queue and processing occurs automatically in a background process, run under your application's supervision tree. For details refer to `Txbox.Mapi.Queue` and `Txbox.Mapi.Processor`.\n\nEach historic miner API response is saved associated to the transaction. The most recent response is always preloaded with the transaction. This allows you to inspect any messages or errors given by miners.\n\n```elixir\niex\u003e {:ok, tx} = Txbox.find(\"6dfccf46359e033053ab1975c1e008ddc98560f591e8ed1c8bd051050992c110\")\niex\u003e tx.status\n%Txbox.Transactions.MapiResponse{\n  type: \"push\",\n  payload: %{\n    \"return_result\" =\u003e \"failure\",\n    \"return_description\" =\u003e \"Not enough fees\",\n    ...\n  },\n  public_key: \"03e92d3e5c3f7bd945dfbf48e7a99393b1bfb3f11f380ae30d286e7ff2aec5a270\",\n  signature: \"3045022100c8e7f9369545b89c978afc13cc19fc6dd6e1cd139d363a6b808141e2c9fccd2e02202e12f4bf91d10bf7a45191e6fe77f50d7b5351dae7e0613fecc42f61a5736af8\",\n  verified: true\n}\n```\n\nFor more examples, refer to the [full documentation](https://hexdocs.pm/txbox).\n\n## License\n\nTxbox is open source and released under the [Apache-2 License](https://github.com/libitx/manic/blob/master/LICENSE.md).\n\n© Copyright 2020 libitx.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flibitx%2Ftxbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flibitx%2Ftxbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flibitx%2Ftxbox/lists"}