diff --git a/NIP-001.md b/NIP-001.md new file mode 100644 index 0000000..1e38997 --- /dev/null +++ b/NIP-001.md @@ -0,0 +1,116 @@ +``` + NIP: 1 + Layer: Applications, PoW + Title: Stratum + Authors: KaffinPX + Status: In-progress +``` + +# Motivation + +This proposal introduces a simplified version of the Stratum protocol for mining pools in the Neptune. The goal is to improve efficiency by transmitting less data and reducing complexity for developers. + +# Specification + +The Stratum protocol mostly adheres to the [JSON RPC 2.0](https://www.jsonrpc.org/specification) specification. + +Communication happens over a bidirectional channel of TCP with messages encoded as JSON with `LF` delimiter—in this document written as `\n`. + +Since requests can be processed in any order, each request should have an unique id. This allows for matching each request with its corresponding response. Responses must include the same id as the request they are replying to. + +If a request doesn't have a specific response and didn't fail, it should return `true`. Additionally, notifications sent by the server should not include an `id`. + +### Methods + +- [subscribe](#subscribe) +- [authorize](#authorize) +- [notify](#notify) +- [submit](#submit) + +### Protocol flow + +The following shows what a session might look like from subscription to submitting a solution. + +``` +Client Server + | | + | ----------- subscribe ------------> | + | ----------- authorize ------------> | + | | + | <------------- notify ------------- | + | | + | -------------- submit ------------> | +``` + +### Errors + +Whenever a call triggers an error, the response must include an `error` field which maps to a **list** of the following values: + +- [ `code`: an integer representing the error code ] +- [ `message`: a string describing the error ] + +For example: + +``` +{"id": 10, "result": false, "error": [21, "Unknown template"]} +``` + +Errors should be identified by their code, and applications should handle errors based on this code, not the message. +In addition to the error codes defined in the JSON RPC 2.0 specification, the following error codes are available: + +- `20` - Other/Unknown +- `21` - Header not found (stale) +- `22` - Duplicate share +- `23` - Low difficulty share +- `24` - Unauthorized worker +- `25` - Not subscribed + +The `message` field should be a brief description of the error for easy understanding. + +#### subscribe + +The subscribe method allows a client to indicate its interest in receiving template notifications with an address from the server. This method can include telemetry data about the miner's software. + +Can be used multiple times for replacing the address as reauthorization. + +##### Request +``` +{"id": 0, "method": "subscribe", "params": ["nolgat1ajggtp8dzdhjdk3vw4nyu8yuzyrrv6ktx3d83wqkdr93972c7fnj0ascpkkn7aeexl0nxrp5wg3zap7kyqrwy5hnhs39q9uhkhvjxpv0zj2flxc5mvpdymnp2zzptz3t6j59zfzjuax89ajhvxj30mv0ht99wuvaq7rsv84n36cljnzgpjz4rgjyc3f6dzj5aay3e4llcvq9cklj0u4ms885jck7hyhfrxfp23kanqc997a9en3c845hre0avdhly0mqeqk7ygrsssldawccuhwsk206mafqyafysrj8ajmgqh2cnwj69pzetqmhht53vjltftj09edee8mduck7vrech885jdwztxad5c4497eh93n368tdk95qyr0fgffxm23vyjnrp5rj20kms3jx7k4hs8hjd4glh5pef7yvfydky59c82zhcazl2tx5jfunzkzy6ufx04wrz38c0gnwvl55hpx869amc60ar7yw2w7tk65l4vg7m3yr7gczlqu6hnszeulrkcaa5ur5y82dug2uhvkle89m5w356pad4dgp64pckuvawkuc6vw8ccks30uruygvcf38g8ujq39hle7ezvztpawjqaqslnu4tn7c4um9sddfje55eteyfskf7t3plpzeculnle5hjfuaalthsfs9ya5w3f06rwewqdyhapmthx3je0zjxxa6skkl6vtwty2ghqe9cr7vzz33jcq8mzfsltzj9zzr93dqgu5x44cjnkhpv2g8crn79a6sjrkeudtwnqlekvstv352hwcznwrv6222smwcejx4e2p68t6na47hentj8dzaje0n8v7tmwuvplwwrnlw2z3c98yzruy6llp96499nfmmlhkefglpdpzndf2xqxu9z98qtmvqyct9pplyrj7wza2p0whr822ypsfugdytwk7hkkt8kshse7qxjqr2zphmsq4cagstx3v69dkras6c2rtjtf68lpwt8a5say4fgyp09dnjdq7rpz449s3w7e7grapcj7nnmqhq2080u8yy2hzajyxq2c4p7v8sg42qyueeynlpt5vp5sp7wwdmzr29a6atwlh22ztfffhewuhpehfy3ecqm824geta2qvd0934nj4qznry397qjy5leg3kfxt6lw6k3frf70yx8f4d26wqyelgy3j3z2m5jczmmn3yncnp7vt0s6sk8zn9eggg7e3d4acaha668txhha9c4vcw3ljgk35vajprptg605ckz97g8mtg4mlv5vsmfktcc8r0005ur4znpmg8kun656a4aj9akxeyy8rqtpd3e2mg374sgpwsrcq2kmys9cpxh7ajwr9eynnqw0dga082464hhzhzapdmldh9xhrk96nepdgjyl7vs6p9c5xcx9u34dltg3gh6n2fuu0ezddtvhp8yx42xchpxqewqefasaywceeavupaqnugmz8g60r2rzgpw86qs37940m3rsz7xh35pgq6dmd6remjm4keyzkcsd64dvsqu0v4h7y396zn87x0f37rwawme0fdum3p6n3k0uc7xl28tkt2sdh6qrngtpdjd7wkpfu85uwcyvwmufrh7498t98fklh6tshneldnvyl3t67r5gp6u6q303x2834d42udvsj2j30cc6qvncuuakkqn8u33vqj3wewfaee7a5v7xsjy5qcanx9gyth6pdtr94exzkc7xnlwh3hxxzq80xq2up6c7rhxqr9z9c84euwmng3u85pt0z72udldqlunc2d7yhf7pdxxe4vplr8qq9pd7qh5y324alxrtgs3rrkd78e92s587gq8u8p327z2xs9kkczwx4977ge92grftnftmyn9q69v564kxsf33a0tft80njgpysgpuz8nlcqceedqzj7yv35gw2tjsu5zlgz528maa8r2e29pq4gpdd5fge3war4kjvstl8xg5kzvmafjjqd2xashf9yhacccvvrz3w4hwddmxm53mc5d45vup6htpwlqzptz4t477vk7vgwu8me8tf5rywmeyfqr9qqlfql6l55wve2w3rkffphcy7kuxcyxl4z9e057d0gyk7gmak7ye3fphz9qr09p23p50g0jd7g62usx34294vamweh84vn7zfvv3e9nu48w6qwka5havvufumjzju392mw3dhpnucfdkjfhrq8euyhjecz0ul6ak04qke3elumujhq45cvg7jt3j7re0g4mm3geyrkx50uhequ6ezyz80nrx0a3zjunggyfhhgyjprynqctk4057jn0wnpjsfrl55tmzn9dd909m6agekhgwdqrnwncn7yayzqphzjww6t6jxsvlcmwylqem9w4ta3whtjzr9ks69fdn5w78dl3sk5ljmtrahuw68tv8242x83vruccwfrycaaefx6a7fnc0rsp45wucgsdy9m2z0zzgtdq8h29el83xds3cpr8mu7tqxnwhlej4eh2w52tyzccju0hl8xpnvs79tmhatynmwl3pkrrmv0atgy8z3apjmtavwu94hlar54yay8w7ykzmalr9f24jvapf9ar9rll5k9xehma6wfevqe3tfcq98daa0pwwqsz2j8sdr7kh46nf3hjl76g4ys0shkdh29qk8rf384kwhwfh00p7jmchuly70p3kgr2cqskvpth8j70dga9s0a7prfp6dy4uu03utpx0tjgk63aq6gcfjh5r2h5k54hl6stca7s83t5w5h6tt7kn6m65ug43vhmkzzhd4ceyyrurn8r3y8ft8qsh4dcgm9rmw50v5s2xq7w4m45d9aa4fmlu4tde6gem9cqq739lyrhdqetj4xm49uw0g50af7n68v9cwah5c68gj4e80legfquektrtqf0kvjz0j9j55ajvyn5fz46vexxm7r923l2ztwtk29z73glwcdwk3pfkqh6t24f7wvnmkzn38xv3mfvmktvptnyt922ssta78w6exmfqg5432sd6ff6xn47r9ctnc20c5puvfpqtga9tjuvryssflh2kp5tmcpm4d3ps3fem5kyh5up95kl5k60wdtd820j3r20f7a057ncah2reerhpgdjrhqtsulgd55h5xadmvz884uta3l6aljf0ezt6fkjncflh8sy2584dwuntkdnp79ws9kq9ess0lu3ug7w70vyc99ph554afmu9kdv2texj0gwx0ypeggfhv05n2rrjgvzd95ww3qqg2evu7fzquuxyskfrtutnn9fmnsddujvy9yvh8lhmdqnyt63jh40njy4g6k9ey77g8r2sapjzsgycnv6f9w5ayhldwhz3s2gwlggz3qya07q8hd4rp0ax2tjk2s8ewjke5ed3myjyc5nfqxhv0s083palutfa7wrym336u3sqqntel9r7mevvusz9ksp00y0c2uytvmh6umavtzsd28puf0e4vd9xemy6kf4x5", "NeptuneMiner/1.0.0"]} +``` + +#### authorize + +The authorize method is used by the client to authenticate its workers with the server, optionally using a worker name. Upon successful authorization, the server responds with an assigned ID and difficulty for the worker. + +##### Request +``` +{"id": 1, "method": "authorize", "params": ["Miner1"]} +``` + +##### Response +``` +{"id": 1, "result": [0, "1000000"]} +``` + +#### notify + +The notify method is used by the server to send a new mining template to the client. This template includes the id, kernel and header auth path of the block. May also include a difficulty if network conditions are changed. + +##### Request +``` +{"method": "notify", "params": ["78e511850e70fbad2e2752f9c04fc0252b02ecdb8693315179a4171fd24a27c1d5b1f3e198ceb3b0", ["47dc98b2b77d59e8eb49a039a23f188fc15f014d1d22c0a736fa5282967c1ad50b6a2df6dbf08470","7b4cbcf1302380cd162481ff5ab2a6dfcec0d5b1163cbb9e210d2212d10a45cbf37d23e59cb046b4"], ["3250a526b6782d867c16f4a8c629c10f4bb75a59bbba1450645cf961e0258606ef39aa61998f7462","696f64348ac3f78b0cd8b840b42d1643b3e7c81eaab69bc507f6d8c883d7bdbf4fac793ba16c04e9","cdaebf9e668877e5064bee6d5f106d5ce8e0147e431db7d16fc6d255b6b75000caafdc84715e14ab"], "1500000"]} +``` + +#### submit + +The submit method allows the client to submit a completed template back to the server. The submission includes the worker id, the block id and the solution (nonce). The server may respond with an updated difficulty for the worker. + +##### Request +``` +{"id": 2, "method": "submit", "params": [0, "8e42cac2061d8341f4147de0db16bfadbc66859e2b29bc01915eb60452f5ef97", "47dc98b2b77d59e8eb49a039a23f188fc15f014d1d22c1a736fa5282967c1ad50b6a2df6dbf08470"]} +``` + +##### Response +``` +{"id": 2, "result": "2000000"} +``` \ No newline at end of file