diff --git a/docs/src/architecture/.pages b/docs/src/architecture/.pages index 7ceda85940e..4120ce54fd7 100644 --- a/docs/src/architecture/.pages +++ b/docs/src/architecture/.pages @@ -12,3 +12,4 @@ nav: - 10_quality_requirements.md - 11_technical_risks.md - 12_glossary.md + diff --git a/docs/src/architecture/08_concepts/gateway/concrete.md b/docs/src/architecture/08_concepts/gateway/concrete.md new file mode 100644 index 00000000000..6508b915fbe --- /dev/null +++ b/docs/src/architecture/08_concepts/gateway/concrete.md @@ -0,0 +1,126 @@ +--- +icon: material/hub +--- + +# Pseudo code + +Building blocks in the form of *pseudo code*; +Intended to make the conceptual design more concrete; not setting rules. + +## Node + +Restart node with new config + +```rust +fn restart_node(config: Config) -> Result<(), Err>{ + // graceful restart +} +``` + +## Config + +Check if config exists; all orchestration is coordinated via the DB, more specifically the config. + +```rust +fn config_exists(db: DBHandler) -> Option { + // lock db + // if config exists { Some(config) } + // else { None } + // Resource acquisition is initialization: drop trait -> unlock db +} +``` + +Node polls for config until it exists in database + +```rust +fn poll_config(db: DBHandler) -> Option { + loop { + if let Some(r) = config_exists(db) { + return Some(r) + } + } +} +``` + +Check if config has been updated + +```rust +fn config_updated(db: DBHandler) -> Option { + // lock db + // if config updated { Some(config) } + // else { None } + // Resource acquisition is initialization: drop trait -> unlock db +} +``` + +## Updates + +Continually race to update database + +```rust +fn index_follower_data(db: DBHandler, stream: FollowerIo)-> Result<(), Err> { + loop { + if database_ready_to_update(db) { + update_database(db, stream) + } + } +} +``` + +Check most recent update on cardano update table +If it falls within the threshold boundary, node should update db with latest data + +```rust +fn database_ready_to_update(db: DBHandler) -> bool { + // lock db + // let last_updated = CardanoUpdateTable() + // return update_threshold(last_updated) + // Resource acquisition is initialization: drop trait -> unlock db +} +``` + +Update database with follower data + +```rust +fn update_database(db: DBHandler, stream: FollowerIo) -> Result<(), Err> { + // lock db + while let Some(block) = stream.next().await { + let metadata = parse(block); + db.insert(metadata); + } + // Resource acquisition is initialization: drop trait -> unlock db +} +``` + +Parse block + +```rust +fn parse(block: Block) -> Result { + // extract era, unspent transaction output, spent Transactions and registration metadata +} +``` + +Calculate if threshold conditional has been met + +```rust +fn update_threshold(last_updated: ThresholdMetric) -> bool { + // threshold calculation + // define conditional +} +``` + +## Follower + +* Start follower with specified networks + +* Stream blocks from given (slot,epoch) + +## Syncing + +Nodes race to update + +## Contention + +## Multiple nodes + +## Roll backs diff --git a/docs/src/architecture/08_concepts/gateway/mechanics.md b/docs/src/architecture/08_concepts/gateway/mechanics.md new file mode 100644 index 00000000000..5c6580c57a9 --- /dev/null +++ b/docs/src/architecture/08_concepts/gateway/mechanics.md @@ -0,0 +1,71 @@ +--- +icon: material/airplane-cog +--- + +# Initial blueprint + +```mermaid + stateDiagram-v2 + state if_state <> + Node -->if_state + if_state --> node : config exists + if_state --> Node: config does not exist + + + note right of node + Indexing blockchain data provided by follower + end note + + + note left of node + checkConfig = thread A + end note + + + note right of node + checkDB = thread B + end note + + + note right of Node + Orchestration is coordinated via the config + end note + + state Node { + init --> init: try until config exists + } + + state Follower { + [*] + } + + state node { + checkConfig-->Database: release + Database-->checkConfig: wait + + checkDB-->Database: release + Database-->checkDB: wait + + State checkConfig{ + Tick --> Updated + Tick --> NoChange: + Updated --> Restart: stop all followers cleanly + Restart --> Tick: Restart with new config + NoChange--> Tick + } + State checkDB{ + tick --> UpdateThreshold + UpdateThreshold --> tick: data is fresh + UpdateThreshold--> Follower: data is stale + updateDB --> tick + updateDB-->Follower + Follower -->updateDB + } + state Database{ + Unlocked --> Locked + Locked--> Unlocked + } + } +``` + +:construction: Design is still active and not final :construction: