search

stratum-mining / sv2-spec

Stratum V2 Specification
58 stars 30 forks source link

cleanup / rewrite JD Protocol specs #77

Open plebhash opened 2 months ago

plebhash commented 2 months ago

Our JD Protocol specs are somewhat outdated. Some things to be done:

plebhash commented 2 months ago

I have some drafts so I'd like to assign this to myself, but it seems I don't have rights on this repo.

@pavlenex can you assign this to me please?

plebhash commented 1 month ago

Discussion ref: https://github.com/stratum-mining/stratum/discussions/911#discussioncomment-9552479

plebhash commented 1 month ago

I just noticed that the hosted specs on stratumprotocol.org are not synced with https://github.com/stratum-mining/sv2-spec

One example: 6.1.4 DeclareMiningJob (Client -> Server)

image image image

what is on 06-Job-Declaration-Protocol.md:

| Field Name                  | Data Type             | Description                                                                                                                                                                                                                                                                                                                                                                                                                  |
| --------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| request_id                  | U32                   | Unique identifier for pairing the response                                                                                                                                                                                                                                                                                                                                                                                   |
| mining_job_token            | B0_255                | Previously reserved mining job token received by AllocateMiningJobToken.Success                                                                                                                                                                                                                                                                                                                                              |
| version                     | U32                   | Version header field. To be later modified by BIP320-consistent changes.                                                                                                                                                                                                                                                                                                                                                     |
| coinbase_tx_prefix         | B0_64K                 | The coinbase transaction nVersion field                                                                                                                                                                                                                                                                                                                                                                                       |
| coinbase_tx_suffix         | B0_64K                 | Up to 8 bytes (not including the length byte) which are to be placed at the beginning of the coinbase field in the coinbase transaction                                                                                                                                                                                                                                                                                      |
| tx_short_hash_nonce         | U64                   | A unique nonce used to ensure tx_short_hash collisions are uncorrelated across the network                                                                                                                                                                                                                                                                                                                                   |
| tx_short_hash_list          | SEQ0_64K[SHORT_TX_ID] | Sequence of SHORT_TX_IDs. Inputs to the SipHash functions are transaction hashes from the mempool. Secret keys k0, k1 are derived from the first two little-endian 64-bit integers from the SHA256(tx_short_hash_nonce), respectively (see bip-0152 for more information). Upstream node checks the list against its mempool. Does not include the coinbase transaction (as there is no corresponding full data for it yet). |
| tx_hash_list_hash           | U256                  | Hash of the full sequence of SHA256(transaction_data) contained in the transaction_hash_list                                                                                                                                                                                                                                                                                                                                 |
| excess_data                 | B0_64K                | Extra data which the Pool may require to validate the work (as defined in the Template Distribution Protocol)
GitGab19 commented 3 weeks ago

Here a suggestion for the SubmitSolution message description:

"Sent by the client as soon as a valid block is found, so that it can be propagated also by the server, which is directly connected to its own Bitcoin node. In the meantime the block is transmitted to the network by the client as well, through the SubmitSolution defined in Template-Distribution-Protocol. In this way a valid solution is immediately propagated on both client and server sides."

@plebhash let me know if you think it's enough or not

plebhash commented 3 weeks ago

Here a suggestion for the SubmitSolution message description:

"Sent by the client as soon as a valid block is found, so that it can be propagated also by the server, which is directly connected to its own Bitcoin node. In the meantime the block is transmitted to the network by the client as well, through the SubmitSolution defined in Template-Distribution-Protocol. In this way a valid solution is immediately propagated on both client and server sides."

@plebhash let me know if you think it's enough or not

looks good, thanks!

whenever we're working on the PR for this issue, I'd also add something like: "This message doesn't elicit any Success or Error response, so it works as fire-and-forget"

plebhash commented 1 week ago

there's an outdated reference to Job Distribution Protocol on the protocol field of SetupConnection

https://stratumprotocol.org/specification/03-Protocol-Overview/#361-setupconnection-client---server