Skip to content

Instantly share code, notes, and snippets.

@Sansh2356

Sansh2356/detailed_flow.md

Last active September 8, 2026 07:30
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save Sansh2356/5b59a10884df63639dbe4bb119f3b155 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save Sansh2356/5b59a10884df63639dbe4bb119f3b155 to your computer and use it in GitHub Desktop.
Download ZIP
SV2 integration workflow
Raw
detailed_flow.md 
flowchart TB

%% =======================
%% MINER LAYER
%% =======================

SV1[SV1 Miner<br>Stratum V1 TCP]
SV2[SV2 Miner<br>Stratum V2 TCP Encrypted]

%% =======================
%% TRANSLATOR PROXY
%% =======================

subgraph TPROXY[TRANSLATOR PROXY]
direction TB

    subgraph SV1SERVER[SV1 Server Socket]
        SV1_IN[Inbound<br>mining.subscribe<br>mining.authorize<br>mining.submit]
        SV1_OUT[Outbound<br>mining.notify<br>mining.set_difficulty<br>submit result]
    end

    subgraph SV2UP[SV2 Channel Manager Upstream]
        SV2_TO_POOL[To Pool<br><br>SetupConnection<br><br>OpenStandardMiningChannel<br><br>SubmitSharesStandard]
        SV2_FROM_POOL[From Pool<br><br>SetupConnection.Success<br><br>OpenMiningChannelSuccess<br><br>NewMiningJob<br><br>SetNewPrevHash<br><br>SubmitSharesSuccess or Error<br><br>SetTarget]
    end

    subgraph BRAID[Braidpool Module]

        subgraph CONS[Braid Consensus Engine]
            CONS1[Receive SubmitSharesSuccess]
            CONS2[Create Bead from validated share]
            CONS3[Extend Braid DAG]
            CONS4[Trigger P2P announce]
        end

        subgraph P2P[P2P Event Loop]
            P2P1[BeadRequest and BeadResponse]
            P2P2[Floodsub messages]
        end

        subgraph DB[Database Handler]
            DB1[Insert bead]
            DB2[Select beads for sync]
        end
    end
end

%% =======================
%% POOL
%% =======================

subgraph POOL[POOL]
direction TB

    subgraph DOWNSTREAM[Downstream Channel Manager]
        DS_IN[Inbound<br>SetupConnection<br>OpenStandardMiningChannel<br>OpenExtendedMiningChannel<br>SubmitSharesStandard<br>SubmitSharesExtended]
        DS_OUT[Outbound<br>SetupConnection.Success<br>OpenStandardMiningChannelSuccess<br>NewMiningJob or Extended<br>SetNewPrevHash<br>SubmitSharesSuccess or Error<br>SetTarget]
    end

    VALIDATE[Validate Share]
    DIFF[Difficulty Adjuster]
    ACCOUNT[Accounting]

    subgraph TEMPLATE[Coinbase and Template Constructor]
        COINBASE[Coinbase Outputs<br><br>OP_RETURN commitment<br><br>Witness commitment<br><br>Miner payouts]
    end

    IPC[Template Receiver<br>getblocktemplate<br>submitblock]
end

CORE[Bitcoin Core<br>Mempool<br>Block Index<br>UTXO Set]

%% =======================
%% CONNECTIONS
%% =======================

SV1 --> SV1SERVER
SV2 --> DOWNSTREAM

SV1SERVER --> SV2UP
SV2UP --> DOWNSTREAM

SV2UP --> CONS
CONS --> P2P
CONS --> DB

DOWNSTREAM --> VALIDATE
VALIDATE --> DIFF
VALIDATE --> ACCOUNT
ACCOUNT --> TEMPLATE
TEMPLATE --> IPC
IPC --> CORE

DS_OUT --> SV2UP
SV2UP --> SV1SERVER
Loading
Raw
general_component_flow.md 
---
title: GENERAL COMPONENT FLOW
---

    flowchart TD

    %% Miner Layer
    SV1[SV1 Miners]
    SV2[SV2 Miners]

    %% Translator Proxy
    subgraph TPROXY["Translator Proxy (tproxy)"]
        CONSENSUS["Braid Consensus Engine"]
        P2P["P2P Event Loop (libp2p)"]
        DB[("Database Persistence")]
    end

    %% Pool Layer
    POOL["SV2 Pool"]
    TEMPLATE["Template Receiver (Bitcoin Core IPC)"]

    %% Bitcoin Core
    CORE["Bitcoin Core Node"]

    %% Braidpool Network
    NETWORK["Braidpool P2P Network"]

    %% Connections
    SV1 --> TPROXY
    SV2 --> TPROXY

    TPROXY --> POOL
    TPROXY --> CONSENSUS

    CONSENSUS --> DB
    CONSENSUS --> P2P

    P2P --> NETWORK

    POOL --> TEMPLATE
    TEMPLATE --> CORE
Loading
Raw
general_flow_v1.md 
---
config:
  layout: fixed
---
flowchart LR
 subgraph P2P["P2P Network"]
        BOOT["Boot node\n(offloaded at VM)"]
        PEER1["Peer 1"]
        PEER2["Peer 2"]
        PEERN["Peer N"]
  end
 subgraph SWARM["Network Swarm"]
        NS["Network Swarm"]
  end
 subgraph BRAID["Braid-node"]
        BN["Braid-node (event-based mgmt)"]
  end
 subgraph IPC["IPC Template Consumer"]
        IC["IPC template<br>consumer<br>(mpsc channel buffer)"]
  end
 subgraph CAPNP["CapnProto IPC"]
        CI["CapnProto IPC<br>client interface"]
  end
 subgraph STRATUM["Stratum Service"]
        SS["Stratum service"]
        JN["Job notifier"]
        M1["Miner 1"]
        M2["Miner 2"]
        MN["Miner N"]
  end
 subgraph QUEUE["Priority Queue</br></br>"]
        Q1["Queue 1"]
        Q2["Queue 2"]
        Q3["Queue 3"]
  end
    BOOT -- Subscribe to bead Announce --> PEER1
    BOOT -- Request nearest peers and update DHT + floodsub --> PEER2
    BOOT --> PEERN
    PEER1 -- Broadcast valid bead via floodsub --> NS
    PEER2 --> NS
    PEERN --> NS
    NS -- Establish connection with swarm --> BN
    BN -- Init &amp; forward valid<br>bead from stratum --> IC
    BN -- "Forward template to<br>stratum via Braid-node" --> IC
    IC -- Reconstruct coinbase<br>&amp; merkle path with<br>braid pool commitment --> CI
    CI -- Publish IsSynced --> Q1 & Q2
    CI -- Publish / getback Template --> Q3
    Q1 -- "Priority-based<br>request queuing" --> BTC["bitcoin-node<br>(unix:/tmp/bitcoin-ipc.sock)"]
    Q2 --> BTC
    Q3 --> BTC
    BTC -. "Received template only if bitcoin-node synced<br>(SUCCESS)" .-> CI
    BTC -. Connection closed<br>(RECONNECT) .-> CI
    SS -- "Async multi-threaded architecture" --> BN
    SS --> JN & M1 & M2 & MN
    JN -.-> BN
Loading
Raw
overall_braidpool_flow_sequence.md 
sequenceDiagram

%% =====================================================
%% BRAIDPOOL MINING LIFECYCLE
%% =====================================================

participant BTC as Bitcoin Node
participant IPC as Cap'n Proto IPC Client
participant TC as Template Consumer
participant BN as Braid Node Core
participant TA as Template Assembler
participant JN as Job Notifier
participant ST as Stratum Server
participant M as Miner

%% --- Template Update Phase ---
BTC->>IPC: Publish new block template
IPC->>TC: Forward template event
TC->>BN: Notify template update

%% --- Template Construction ---
BN->>TA: Request template reconstruction
TA->>TA: Rebuild coinbase
TA->>TA: Insert MPC commitments
TA->>TA: Finalize block template

%% --- Job Creation ---
TA->>JN: Send finalized template
JN->>ST: Create new mining job

%% --- Job Distribution ---
ST-->>M: mining.notify (new job)
M->>ST: mining.subscribe
M->>ST: mining.authorize

%% --- Mining Phase ---
loop Mining Work
    M->>ST: Submit share
    ST->>BN: Forward share
    BN->>BN: Validate share
end

%% --- Block Found Scenario ---
M->>ST: Submit valid block share
ST->>BN: Forward block candidate
BN->>BTC: Submit block

%% --- Network Propagation ---
BTC-->>BN: Block accepted
BN-->>ST: Notify new block
ST-->>M: Send new job
Loading
Raw
p2p_communication_flow.md 
---
title: P2P COMMUINCATION FLOW
---

sequenceDiagram

    participant L as tproxy (Local)
    participant N as Braidpool P2P Network
    participant R as tproxy (Remote Peer)

    L->>N: 1. Startup or IBD detected

    L->>N: 2. Kademlia find peers

    N-->>L: 3. Bootstrap response

    L->>R: 4. BeadRequest GetTips

    R-->>L: 5. BeadResponse Tips

    L->>R: 6. BeadRequest GetBeadsAfter(tips)

    R-->>L: 7. BeadResponse Beads

    L->>L: 8. Validate bead
    L->>L: Extend local Braid
    L->>L: Persist to DB

    L->>N: 9. Floodsub announce new local bead

    N->>R: 10. Propagate to all peers
Loading
Raw
share_submission_flow.md 
---
title: SHARE SUBMISSION FLOW
---

sequenceDiagram
    participant M as SV1 Miner
    participant T as tproxy
    participant P as Pool
    participant C as Bitcoin Core
    participant N as Other Peers (P2P)

    M->>T: 1. mining.submit

    T->>P: 2. Convert to SV2 Frame (SubmitSharesStandard)

    P->>P: 3. Validate PoW
    P->>P: 4. Adjust Difficulty
    P->>P: 5. Update Accounting

    P-->>T: 6. SubmitSharesSuccess (validated_share_result)

    P->>C: 6a. submitblock if share meets network target

    T->>T: 7. Convert Share to Bead
    T->>T: 8. Extend Local Braid
    T->>T: 9. Persist to DB

    T-->>N: 10. Propagate via P2P

    T-->>M: 11. mining.submit result (RPC)
Loading
Raw
template_flow.md 
---
title: NEW TEMPLATE FLOW
---

sequenceDiagram

    participant C as Bitcoin Core
    participant P as Pool
    participant T as tproxy
    participant M as SV1 Miner

    C->>P: 1. New tip detected (ZMQ/IPC notify)

    P->>C: 2. getblocktemplate (via IPC)

    C-->>P: 3. BlockTemplate

    P->>P: 4. Build coinbase with Braidpool commitment, payout outputs, witness commitment
    P->>P: 5. Calculate merkle root

    P->>T: 6. NewMiningJob (SV2)

    T->>M: 7. Convert to SV1 mining.notify
Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment