{"id":30861087,"url":"https://github.com/plebhash/sv2-services","last_synced_at":"2026-04-29T18:32:45.964Z","repository":{"id":284603907,"uuid":"906835212","full_name":"plebhash/sv2-services","owner":"plebhash","description":"🦀 Service-oriented framework for Bitcoin mining over Stratum V2 Reference Implementation ⛏️","archived":false,"fork":false,"pushed_at":"2025-10-25T15:13:35.000Z","size":758,"stargazers_count":4,"open_issues_count":4,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-03-06T17:43:46.627Z","etag":null,"topics":["bitcoin","mining","mining-pool","mining-pool-development","stratum","stratum-pool","stratum-protocol","stratum-proxy","tokio","tower"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/plebhash.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-12-22T03:38:07.000Z","updated_at":"2025-10-25T15:13:38.000Z","dependencies_parsed_at":"2025-03-26T18:40:41.396Z","dependency_job_id":"5a9c79ca-1f2d-414b-b716-f3ec41a1528d","html_url":"https://github.com/plebhash/sv2-services","commit_stats":null,"previous_names":["plebhash/tower-stratum"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/plebhash/sv2-services","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plebhash%2Fsv2-services","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plebhash%2Fsv2-services/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plebhash%2Fsv2-services/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plebhash%2Fsv2-services/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/plebhash","download_url":"https://codeload.github.com/plebhash/sv2-services/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plebhash%2Fsv2-services/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32439179,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T18:12:22.909Z","status":"ssl_error","status_checked_at":"2026-04-29T18:11:33.322Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["bitcoin","mining","mining-pool","mining-pool-development","stratum","stratum-pool","stratum-protocol","stratum-proxy","tokio","tower"],"created_at":"2025-09-07T16:47:41.674Z","updated_at":"2026-04-29T18:32:45.945Z","avatar_url":"https://github.com/plebhash.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\nsv2-services\n\u003cbr\u003e\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://codecov.io/gh/plebhash/sv2-services\" \u003e \n    \u003cimg src=\"https://codecov.io/gh/plebhash/sv2-services/graph/badge.svg?token=6ME38GTAIP\"/\u003e \n  \u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n🦀 Service-oriented framework for Bitcoin mining over \u003ca href=\"https://github.com/stratum-mining/stratum\"\u003eStratum V2 Reference Implementation\u003c/a\u003e ⛏️\n\u003c/p\u003e\n\nThis crate aims to provide a robust Service-oriented framework for building Bitcoin mining apps based on:\n- [Tokio](https://tokio.rs/): an asynchronous runtime for Rust\n- [Stratum V2 Reference Implementation](https://github.com/stratum-mining/stratum): the reference implementation of the Stratum V2 protocol\n\nThe goal is to provide a \"batteries-included\" approach to implement stateful Sv2 applications.\n\nNote: currently development focus is on Stratum V2 (Sv2). While theoretically possible, Sv1 integration is not planned for the near future.\n\n# Scope\n\n`sv2-services` provides Service abstractions for building apps to be executed under `tokio` runtimes.\n\nThey can be divided in two categories:\n- `Sv2ClientService`\n- `Sv2ServerService`\n\nBoth implement the `Sv2Service` trait, which unifies abstractions around the notion of a Sv2 Service.\n\nThe user is expected to implement handlers for the different Sv2 subprotocols, and use simple high-level APIs to compose Sv2 applications that are able to exchange Sv2 messages and behave according to the handler.\n\n## Client-side\n\n![](./docs/Sv2ClientService.png)\n\n`Sv2ClientService\u003cM, J, T\u003e` is a `Sv2Service` representing a Sv2 Client.\n\nIt's able to establish a TCP connection with the Server and exchange `SetupConnection` messages to negotiate the Sv2 Connection parameters according to the user configurations.\n\nNoise encryption over the TCP connections is optional.\n\nIt listens for messages from the server, generating `type Event = Sv2ClientEvent` for a `Sv2Service::handle`, which triggers execution of the different subprotocol handlers (implemented by the user) and returns some `type Outcome = Sv2ClientOutcome`.\n\nThe user is expected to set the different generic parameters `\u003cM, J, T\u003e` with implementations for the handler traits of the different subprotocols:\n- `M` must implement `trait Sv2MiningClientHandler`\n  - example use-cases:\n    - Sv2 CPU miner\n    - Sv2 Proxy\n- `J` must implement `trait Sv2JobDeclarationClientHandler`\n  - example use-cases:\n    - Sv2 Job Declarator Client\n- `T` must implement `trait Sv2TemplateDistributionClientHandler`\n  - example use-cases:\n    - Sv2 Pool\n    - Sv2 Job Declarator Client\n    - Sv2 Solo Mining Server\n\nFor the subprotocols that are not supported, Null handler implementations are provided:\n- `NullSv2MiningClientHandler`\n- `NullSv2JobDeclarationClientHandler`\n- `NullSv2TemplateDistributionClientHandler`\n\nWhenever `Sv2ClientService\u003cM, J, T\u003e` is loaded with one of these Null handler implementations, the service will NOT support such subprotocol.\n\n## Server-side\n\n![](./docs/Sv2ServerService.png)\n\n`Sv2ServerService\u003cM, J, T\u003e` is a `Sv2Service` representing a Sv2 Server.\n\nIt's able to listen for TCP connections and exchange `SetupConnection` messages to negotiate the Sv2 Connection parameters according to the user configurations.\n\nNoise encryption over the TCP connections is optional.\n\nIt listens for messages from multiple clients, generating `type Event = Sv2ServerEvent` for a `Sv2Service::handle`, which triggers execution of the different subprotocol handlers (implemented by the user) and returns some `type Outcome = Sv2ServerOutcome`.\n\nInactive clients have their connections killed and are removed from memory after some predefined time.\n\nThe user is expected to set the different generic parameters `\u003cM, J, T\u003e` with implementations for the handler traits of the different subprotocols:\n- `M` must implement `trait Sv2MiningServerHandler`\n  - example use-cases:\n    - Sv2 Proxy\n    - Sv2 Pool\n    - Sv2 Solo Mining Server\n- `J` must implement `trait Sv2JobDeclarationServerHandler`\n  - example use-cases:\n    - Sv2 Job Declarator Server\n- `T` must implement `trait Sv2TemplateDistributionServerHandler`\n  - example use-cases:\n    - Sv2 Template Provider\n\n\nFor the subprotocols that are not supported, Null handler implementations are provided:\n- `NullSv2MiningServerHandler`\n- `NullSv2JobDeclarationServerHandler`\n- `NullSv2TemplateDistributionServerHandler`\n\nWhenever `Sv2ServiceService\u003cM, J, T\u003e` is loaded with one of these Null handler implementations, the service will NOT support such subprotocol.\n\n## Inter-Service Communication\n\n`sv2-services` supports inter-service communication between a `Sv2ServerService` and a `Sv2ClientService` pair through the sibling IO mechanism. This allows for building complex Sv2 applications that require bidirectional communication between a server and client service running **within the same application**.\n\n`sv2-services` services are called \"siblings\" when they are tightly coupled with a server/client counterpart **within the same application**. This distinction is very important, and should not be confused with server/client communication across the wire, where server and client are actually different applications.\n\nThe notion of sibling services allows for different use-cases, such as:\n- Mining Server + Mining Client (e.g.: Proxy)\n- Mining Server + Template Distribution Client (e.g.: Pool, [`pleblottery`](https://github.com/vinteumorg/pleblottery))\n- Mining Server + Job Declaration Client + Template Distribution Client (e.g.: JDC)\n- Job Declaration Server + Template Distribution Client (e.g.: JDS)\n\n### Sibling Service creation\n\n`Sv2ServerService::new_with_sibling` constructor also returns a `Sv2SiblingServerServiceIo`, which can be fed into constructor `Sv2ClientService::new_from_sibling_io`:\n\n```rust\n// Create a server along with a sibling_io\n//               v\nlet (server, sibling_io) = Sv2ServerService::new_with_sibling_io(\n    server_config,\n    server_m_handler,\n    server_jd_handler,\n    server_td_handler,\n    cancellation_token,\n)?;\n\n// Create a client service using the sibling_io\nlet client = Sv2ClientService::new_from_sibling_io(\n    client_config,\n    client_m_handler,\n    client_jd_handler,\n    client_td_handler,\n    sibling_io, // \u003c- use sibling_io to construct client service\n    cancellation_token\n)?;\n```\n\n### Communication Between Siblings\n\nServices can communicate with their siblings by sending requests via the sibling IO channels, which are triggered with special request variants.\n\nFor example, here's an illustration of a `Sv2ServerService` receiving a `Sv2ServerEvent::SendEventToSiblingClientService`, which results in `Sv2ClientService` receiving some specific `Sv2ClientEvent`.\n\nPlease note that these two sibling services belong to the same application.\n\n```rust\n// Server sending event to its sibling client\nlet response = server.handle(Sv2ServerEvent::SendEventToSiblingClientService(\n    Sv2ClientEvent::SomeEvent(...),\n)).await?;\n```\n\n![](./docs/SendEventToSiblingClientService.png)\n\nAlternatively, here's an illustration of a `Sv2ClientService` receiving a `Sv2ClientEvent::SendEventToSiblingServerService`, which results in `Sv2ServerService` receiving some specific `Sv2ServerEvent`.\n\nPlease note that these two sibling services belong to the same application.\n\n```rust\n// Client sending event to its sibling server\nlet response = client.call(RequestToSv2Client::SendRequestToSiblingServerService(\n    Sv2ServerEvent::SomeEvent(...),\n)).await?;\n```\n\n![](./docs/SendEventToSiblingServerService.png)\n\n# License\n\n[`MIT`](LICENSE)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplebhash%2Fsv2-services","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplebhash%2Fsv2-services","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplebhash%2Fsv2-services/lists"}