Sequence Diagrams

Intent of these diagrams:

1. Show how different modules fit together
2. Map to specific functions/files in the codebase
3. Be easily updatable to limit rot

That 3rd point forced some compromises, namely using Github's mermaid integration for diagrams rather than building the diagram in another tool and uploading an image. Adapting to mermaid's constraints:

• Vertical gray actors are distinct services
• Black "note" boxes reference specific functions in the codebase
• Horizontal arrows represent process-to-process communication or message passing
• opt dotted boxes group related functions and messages for understandability
• loop dotted boxes are used for loops or repeated processes

VDF Calculation

%%{
  init: {
    'theme': 'neutral'
  }
}%%
sequenceDiagram
participant ar_nonce_limiter
participant worker
participant ETS
participant ar_events

Note over ar_nonce_limiter: init/1

opt Query the last N blocks
Note over ar_nonce_limiter: ar_node:get_current_block/1
ETS->>ar_nonce_limiter: ets:lookup(node_state, current)
ETS->>ar_nonce_limiter: ets:lookup(node_state, {block, H})
Note over ar_nonce_limiter: ar_node:get_blocks/2
ETS->>ar_nonce_limiter: ets:lookup(node_state, {block, H})
end

Note over ar_nonce_limiter: start_worker/1
ar_nonce_limiter->>worker: spawn(worker/0)

loop Repeat every second (VDF delay)
Note over ar_nonce_limiter: schedule_step/1
ar_nonce_limiter->>worker: send(compute)
Note over worker: compute/2
Note over worker: ar_vdf:compute/3
Note over worker: ar_mine_randomx:vdf_sha2_nif/5
Note over worker: vdf.cpp:vdf_sha2(...)
worker->>ar_nonce_limiter: send(computed)
ar_nonce_limiter->>ar_events: send(nonce_limiter, computed_output)
end

Loading

Mining

%%{
  init: {
    'theme': 'neutral'
  }
}%%
sequenceDiagram
participant ar_events
participant ar_mining_server
participant io thread
participant hashing thread
participant ETS
participant filesystem
opt Initialization
Note over ar_mining_server: init/1
ar_mining_server->>ar_events: subscribe(nonce_limiter)
ar_mining_server->>io thread: spawn(io thread) - 1 per storage_module
ar_mining_server->>hashing thread: spawn(hashing thread)
end

opt ar_mining_server maintains a priority queue of tasks and processes them sequentially via handle_task/2
ar_events->>ar_mining_server: send(nonce_limiter, computed_output)
Note over ar_mining_server: handle_task/computed_output
ar_mining_server->>hashing thread: send(compute_h0)
end

opt Compute "h0" - a cryptographic hash used as a source of entropy
Note over hashing thread: ar_block:compute_h0/4
Note over hashing thread: ar_mine_randomx:hash_fast/5
hashing thread->>ar_mining_server: send(mining_thread_computed_h0)
end

opt Read recall range(s)
Note over ar_mining_server: handle_task/mining_thread_computed_h0
Note over ar_mining_server: ar_block:get_recall_range/3
ar_mining_server->>io thread: send(read_recall_range)
ar_mining_server->>io thread: send(read_recall_range2)
loop For each recall range, load all the synced chunks from disk
Note over io thread: ar_sync_record:get_next_synced_interval/5
ETS->>io thread: ets:lookup(sync_records, {ID, StoreID})
ETS->>io thread: ets:lookup(SyncRectordType, NextOffset)
Note over io thread: ar_chunk_storage:get_range/3
Note over io thread: ar_chunk_storage:read_chunk
filesystem->>io thread: file:pread/3
io thread->>ar_mining_server: send(io_thread_recall_range_chunk)
end
end

ar_mining_server->>hashing thread: send(compute_h1)

opt Compute "h1" - either the hash of a solution (1 chunk) or input to the a solution hash (2 chunk)
Note over hashing thread: ar_block:compute_h1/3
Note over hashing thread: crypto:hash/3
hashing thread->>ar_mining_server: send(mining_thread_computed_h1)
end

Note over ar_mining_server: handle_task/mining_thread_computed_h1

opt Prepare 1 chunk solution
Note over ar_mining_server: prepare_solution/3
Note over ar_mining_server: ar_wallet:load_key/1
Note over ar_mining_server: ar_data_sync:get_chunk/2
opt Read chunk from disk
Note over ar_mining_server: ar_chunk_storage:get/2
Note over io thread: ar_chunk_storage:read_chunk
filesystem->>io thread: file:pread/3
end

Loading

VDF Server

%%{
  init: {
    'theme': 'neutral'
  }
}%%
sequenceDiagram
participant ar_events
participant ar_nonce_limiter_server_worker
participant VDF Client

loop 1 instance per configured VDF Client
Note over ar_nonce_limiter_server_worker: init/1
ar_nonce_limiter_server_worker->>ar_events: subscribe(nonce_limiter)
end


ar_events->>ar_nonce_limiter_server_worker: send(nonce_limiter, computed_output)

opt POST vdf to a registered client
Note over ar_nonce_limiter_server_worker: push_update/3
Note over ar_nonce_limiter_server_worker: ar_http_iface_cient:push_nonce_limiter_update/2
ar_nonce_limiter_server_worker->>VDF Client: POST /vdf
Note over ar_nonce_limiter_server_worker: push_session/2
Note over ar_nonce_limiter_server_worker: ar_http_iface_cient:push_nonce_limiter_update/2
ar_nonce_limiter_server_worker->>VDF Client: POST /vdf
end

Loading