From d5a286f220368e1f11f3facd79c1d6c4522580b0 Mon Sep 17 00:00:00 2001 From: rob thijssen Date: Wed, 9 Sep 2026 17:04:45 +0300 Subject: [PATCH] feat: account pages, built on the event index MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `/quantus/account/qzp2AxZw…` answers the question the official explorer answers badly: what an address has actually been paid, every reward, back as far as the index has read. Everything comes from this observer's own decoding — no subsquid, no external indexer, nothing that stops working when the node prunes the state behind it. There is no case per event type anywhere in this. `chain_event` gained an `accounts` column filled by the decoder itself, which knows which values are `AccountId32` by registry path — the same knowledge that keeps it from rendering a block hash as an address — so "everything involving this account" is one containment query that already covers pallets nobody has written yet. The frontend labels what it recognises and renders anything else as its own key and value, so a new event type shows up as itself rather than not at all. Events also carry the block's own timestamp now. `block.authored_at` holds the same thing but only for blocks this process was running for, and a payment history that renders "height 412" with no date because the observer was not alive in March is not a history. The preimage and the address are two ends of one identity and each page now links to the other. Address to preimage is a lookup among preimages seen, not a calculation: the derivation runs one way. Verified against mainnet: 13,384 reward events indexed from genesis to the tip, quanpool's page reconciling to 3,784.98 QTC over 12,346 blocks, and transfers rendering their counterparties as linked addresses without a line of code that knows what a transfer is. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01Jp6a8EDar9ueEhAxzep4V5 --- ...1522645c068b692d59cc9a9556a8f5a2bf750.json | 53 +++ ...eb98012ca135a793052adb114c6a8b038608.json} | 20 +- ...5cdb3ed4cd1993552582f409c0081d8ba2fdd.json | 23 ++ ...733d5fa977feb654b8dd56273fa47560908bc.json | 23 ++ ...a29637c663f85c8d9aacc96889492174c0505.json | 21 -- crates/blackbeard-api/src/ingest.rs | 14 + crates/blackbeard-api/src/routes.rs | 136 +++++++- crates/blackbeard-core/src/runtime.rs | 82 ++++- crates/blackbeard-core/src/wormhole.rs | 13 + .../migrations/0005_event_accounts.sql | 38 ++ crates/blackbeard-data/src/store.rs | 165 +++++++-- crates/blackbeard-entities/Cargo.toml | 1 + crates/blackbeard-entities/src/account.rs | 114 ++++++ crates/blackbeard-entities/src/lib.rs | 2 + readme.md | 24 ++ web/src/App.tsx | 14 + web/src/api/generated/AccountDetail.ts | 57 +++ web/src/api/generated/AccountEvent.ts | 49 +++ web/src/api/generated/RewardSummary.ts | 32 ++ web/src/api/rest.ts | 22 ++ web/src/components/AccountPanel.tsx | 329 ++++++++++++++++++ web/src/components/MinerPanel.tsx | 9 +- web/src/index.css | 63 ++++ web/src/lib/format.ts | 46 +++ 24 files changed, 1290 insertions(+), 60 deletions(-) create mode 100644 .sqlx/query-7aa97660367b7b3d2c7d867053b1522645c068b692d59cc9a9556a8f5a2bf750.json rename .sqlx/{query-89288c55f511f60e817045e0fb579b2592236c9dedf86a0e816dbb598b8a6166.json => query-9e9da3f0fa8255b95befdfd158c3eb98012ca135a793052adb114c6a8b038608.json} (64%) create mode 100644 .sqlx/query-abca0800d897a5dea46e424364b5cdb3ed4cd1993552582f409c0081d8ba2fdd.json create mode 100644 .sqlx/query-de6b5ab88ef82f7809c3d380a28733d5fa977feb654b8dd56273fa47560908bc.json delete mode 100644 .sqlx/query-f4954eb7baea34b5121dc516522a29637c663f85c8d9aacc96889492174c0505.json create mode 100644 crates/blackbeard-data/migrations/0005_event_accounts.sql create mode 100644 crates/blackbeard-entities/src/account.rs create mode 100644 web/src/api/generated/AccountDetail.ts create mode 100644 web/src/api/generated/AccountEvent.ts create mode 100644 web/src/api/generated/RewardSummary.ts create mode 100644 web/src/components/AccountPanel.tsx diff --git a/.sqlx/query-7aa97660367b7b3d2c7d867053b1522645c068b692d59cc9a9556a8f5a2bf750.json b/.sqlx/query-7aa97660367b7b3d2c7d867053b1522645c068b692d59cc9a9556a8f5a2bf750.json new file mode 100644 index 0000000..4926bc3 --- /dev/null +++ b/.sqlx/query-7aa97660367b7b3d2c7d867053b1522645c068b692d59cc9a9556a8f5a2bf750.json @@ -0,0 +1,53 @@ +{ + "db_name": "PostgreSQL", + "query": "\n select count(*) as \"count!\",\n coalesce(sum((fields->>'reward')::numeric), 0)::text as \"total!\",\n min(height) as first_height,\n max(height) as last_height,\n min(at) as first_at,\n max(at) as last_at\n from chain_event\n where chain = $1 and accounts @> array[$2]\n and pallet = 'MiningRewards' and variant = 'MinerRewarded'\n ", + "describe": { + "columns": [ + { + "ordinal": 0, + "name": "count!", + "type_info": "Int8" + }, + { + "ordinal": 1, + "name": "total!", + "type_info": "Text" + }, + { + "ordinal": 2, + "name": "first_height", + "type_info": "Int8" + }, + { + "ordinal": 3, + "name": "last_height", + "type_info": "Int8" + }, + { + "ordinal": 4, + "name": "first_at", + "type_info": "Timestamptz" + }, + { + "ordinal": 5, + "name": "last_at", + "type_info": "Timestamptz" + } + ], + "parameters": { + "Left": [ + "Text", + "Text" + ] + }, + "nullable": [ + null, + null, + null, + null, + null, + null + ] + }, + "hash": "7aa97660367b7b3d2c7d867053b1522645c068b692d59cc9a9556a8f5a2bf750" +} diff --git a/.sqlx/query-89288c55f511f60e817045e0fb579b2592236c9dedf86a0e816dbb598b8a6166.json b/.sqlx/query-9e9da3f0fa8255b95befdfd158c3eb98012ca135a793052adb114c6a8b038608.json similarity index 64% rename from .sqlx/query-89288c55f511f60e817045e0fb579b2592236c9dedf86a0e816dbb598b8a6166.json rename to .sqlx/query-9e9da3f0fa8255b95befdfd158c3eb98012ca135a793052adb114c6a8b038608.json index 398a400..61d586d 100644 --- a/.sqlx/query-89288c55f511f60e817045e0fb579b2592236c9dedf86a0e816dbb598b8a6166.json +++ b/.sqlx/query-9e9da3f0fa8255b95befdfd158c3eb98012ca135a793052adb114c6a8b038608.json @@ -1,6 +1,6 @@ { "db_name": "PostgreSQL", - "query": "\n select height, event_index, pallet, variant, phase, extrinsic_index,\n fields as \"fields!\"\n from chain_event\n where chain = $1 and pallet = $2 and variant = $3 and fields @> $4\n order by height desc, event_index desc\n limit $5\n ", + "query": "\n select height, event_index, pallet, variant, phase, extrinsic_index,\n fields as \"fields!\", at, accounts as \"accounts!\"\n from chain_event\n where chain = $1 and accounts @> array[$2]\n and (height, event_index) < ($3, $4)\n order by height desc, event_index desc\n limit $5\n ", "describe": { "columns": [ { @@ -37,14 +37,24 @@ "ordinal": 6, "name": "fields!", "type_info": "Jsonb" + }, + { + "ordinal": 7, + "name": "at", + "type_info": "Timestamptz" + }, + { + "ordinal": 8, + "name": "accounts!", + "type_info": "TextArray" } ], "parameters": { "Left": [ "Text", "Text", - "Text", - "Jsonb", + "Int8", + "Int4", "Int8" ] }, @@ -55,8 +65,10 @@ false, false, true, + false, + true, false ] }, - "hash": "89288c55f511f60e817045e0fb579b2592236c9dedf86a0e816dbb598b8a6166" + "hash": "9e9da3f0fa8255b95befdfd158c3eb98012ca135a793052adb114c6a8b038608" } diff --git a/.sqlx/query-abca0800d897a5dea46e424364b5cdb3ed4cd1993552582f409c0081d8ba2fdd.json b/.sqlx/query-abca0800d897a5dea46e424364b5cdb3ed4cd1993552582f409c0081d8ba2fdd.json new file mode 100644 index 0000000..9b9ea5f --- /dev/null +++ b/.sqlx/query-abca0800d897a5dea46e424364b5cdb3ed4cd1993552582f409c0081d8ba2fdd.json @@ -0,0 +1,23 @@ +{ + "db_name": "PostgreSQL", + "query": "\n insert into chain_event\n (chain, height, event_index, pallet, variant, phase, extrinsic_index,\n fields, accounts, at)\n select chain, height, event_index, pallet, variant, phase, extrinsic_index,\n fields, array(select jsonb_array_elements_text(accounts)), at\n from unnest(\n $1::text[], $2::bigint[], $3::int[], $4::text[],\n $5::text[], $6::text[], $7::int[], $8::jsonb[], $9::jsonb[],\n $10::timestamptz[]\n ) as t(chain, height, event_index, pallet, variant, phase, extrinsic_index,\n fields, accounts, at)\n on conflict (chain, height, event_index) do update set\n pallet = excluded.pallet,\n variant = excluded.variant,\n phase = excluded.phase,\n extrinsic_index = excluded.extrinsic_index,\n fields = excluded.fields,\n accounts = excluded.accounts,\n -- Never overwrite a time we have with one we do not: a\n -- re-index against a node that has since pruned would blank\n -- the history it was meant to confirm.\n at = coalesce(excluded.at, chain_event.at)\n ", + "describe": { + "columns": [], + "parameters": { + "Left": [ + "TextArray", + "Int8Array", + "Int4Array", + "TextArray", + "TextArray", + "TextArray", + "Int4Array", + "JsonbArray", + "JsonbArray", + "TimestamptzArray" + ] + }, + "nullable": [] + }, + "hash": "abca0800d897a5dea46e424364b5cdb3ed4cd1993552582f409c0081d8ba2fdd" +} diff --git a/.sqlx/query-de6b5ab88ef82f7809c3d380a28733d5fa977feb654b8dd56273fa47560908bc.json b/.sqlx/query-de6b5ab88ef82f7809c3d380a28733d5fa977feb654b8dd56273fa47560908bc.json new file mode 100644 index 0000000..16ec0fc --- /dev/null +++ b/.sqlx/query-de6b5ab88ef82f7809c3d380a28733d5fa977feb654b8dd56273fa47560908bc.json @@ -0,0 +1,23 @@ +{ + "db_name": "PostgreSQL", + "query": "\n select b.miner\n from chain_event e\n join block b on b.chain = e.chain and b.height = e.height\n where e.chain = $1 and e.accounts @> array[$2]\n and e.pallet = 'MiningRewards' and e.variant = 'MinerRewarded'\n order by e.height desc\n limit 1\n ", + "describe": { + "columns": [ + { + "ordinal": 0, + "name": "miner", + "type_info": "Text" + } + ], + "parameters": { + "Left": [ + "Text", + "Text" + ] + }, + "nullable": [ + false + ] + }, + "hash": "de6b5ab88ef82f7809c3d380a28733d5fa977feb654b8dd56273fa47560908bc" +} diff --git a/.sqlx/query-f4954eb7baea34b5121dc516522a29637c663f85c8d9aacc96889492174c0505.json b/.sqlx/query-f4954eb7baea34b5121dc516522a29637c663f85c8d9aacc96889492174c0505.json deleted file mode 100644 index 6e74cff..0000000 --- a/.sqlx/query-f4954eb7baea34b5121dc516522a29637c663f85c8d9aacc96889492174c0505.json +++ /dev/null @@ -1,21 +0,0 @@ -{ - "db_name": "PostgreSQL", - "query": "\n insert into chain_event\n (chain, height, event_index, pallet, variant, phase, extrinsic_index, fields)\n select * from unnest(\n $1::text[], $2::bigint[], $3::int[], $4::text[],\n $5::text[], $6::text[], $7::int[], $8::jsonb[]\n )\n on conflict (chain, height, event_index) do update set\n pallet = excluded.pallet,\n variant = excluded.variant,\n phase = excluded.phase,\n extrinsic_index = excluded.extrinsic_index,\n fields = excluded.fields\n ", - "describe": { - "columns": [], - "parameters": { - "Left": [ - "TextArray", - "Int8Array", - "Int4Array", - "TextArray", - "TextArray", - "TextArray", - "Int4Array", - "JsonbArray" - ] - }, - "nullable": [] - }, - "hash": "f4954eb7baea34b5121dc516522a29637c663f85c8d9aacc96889492174c0505" -} diff --git a/crates/blackbeard-api/src/ingest.rs b/crates/blackbeard-api/src/ingest.rs index f4dd603..974d147 100644 --- a/crates/blackbeard-api/src/ingest.rs +++ b/crates/blackbeard-api/src/ingest.rs @@ -748,6 +748,18 @@ async fn index_events( } }; + // The chain's own clock rather than the observer's: an account's rewards + // run back to genesis, and most of them predate this process. One more + // call, and `None` if the node declines — a reward with no date is still a + // reward. + let at = chain + .rpc + .block_timestamp_ms(hash) + .await + .ok() + .flatten() + .and_then(from_millis); + let keep: Vec = decoded .into_iter() .filter(|e| is_indexed(&e.pallet, &e.variant)) @@ -760,6 +772,8 @@ async fn index_events( phase: e.phase, extrinsic_index: e.extrinsic_index, fields: e.fields, + accounts: e.accounts, + at, }) .collect(); diff --git a/crates/blackbeard-api/src/routes.rs b/crates/blackbeard-api/src/routes.rs index 6285174..9fdca71 100644 --- a/crates/blackbeard-api/src/routes.rs +++ b/crates/blackbeard-api/src/routes.rs @@ -16,8 +16,9 @@ use axum::response::{IntoResponse, Response}; use axum::routing::get; use axum::{Json, Router}; use blackbeard_entities::{ - ApiError, BigUintDec, BlockDetail, ChainInfo, ChainSeries, ChainSummary, LeaderboardRow, - MinerDetail, MinerId, MinerSeriesPoint, RecentBlock, Window, + AccountDetail, AccountEvent, ApiError, BigUintDec, BlockDetail, ChainInfo, ChainSeries, + ChainSummary, LeaderboardRow, MinerDetail, MinerId, MinerSeriesPoint, RecentBlock, + RewardSummary, Window, }; use serde::{Deserialize, Serialize}; use tower_http::compression::CompressionLayer; @@ -50,6 +51,7 @@ pub fn router(state: AppState, allowed_origins: &[String]) -> Router { .route("/v1/chains/{chain}/series", get(series)) .route("/v1/chains/{chain}/blocks/{block}", get(block)) .route("/v1/chains/{chain}/miners/{miner}", get(miner)) + .route("/v1/chains/{chain}/accounts/{address}", get(account)) .route("/v1/ws", get(crate::ws::handler)) // Leaderboards are repetitive JSON and compress to a fraction of their // size; the snapshot a browser fetches on first paint is the largest @@ -554,6 +556,136 @@ async fn miner( })) } +/// How many activity rows one page of an account's history carries. +/// +/// Enough that the common case — an account that has mined for a day — is one +/// request, and bounded so that quanpool's hundred thousand rewards do not +/// arrive as a single response. +const ACTIVITY_PAGE: i64 = 100; + +/// Paging cursor: the `(height, event_index)` of the last row already seen. +#[derive(Debug, Deserialize)] +struct ActivityQuery { + before_height: Option, + before_index: Option, +} + +/// One account: what it was paid, and everything else it appears in. +/// +/// Every number here comes from this observer's own index, decoded against the +/// runtime that produced each block — no subsquid, no external indexer, and +/// nothing that needs the chain to still hold the state. +async fn account( + State(state): State, + Path((chain, address)): Path<(String, String)>, + Query(query): Query, +) -> Result, Failure> { + let runtime = state.chain(&chain).ok_or_else(|| unknown_chain(&chain))?; + let account = parse_address(&address)?; + let id = runtime.id(); + + // A cursor is only a cursor with both halves; half of one would silently + // page from event zero of that height and repeat a row. + let before = match (query.before_height, query.before_index) { + (Some(h), Some(i)) => Some((h, i)), + _ => None, + }; + + let totals = state + .store + .account_rewards(&id, &account) + .await + .map_err(database_unavailable)?; + let activity = state + .store + .account_events(&id, &account, before, ACTIVITY_PAGE) + .await + .map_err(database_unavailable)?; + let miner = state + .store + .miner_for_account(&id, &account) + .await + .map_err(database_unavailable)?; + let scan = state + .store + .event_scan(&id) + .await + .map_err(database_unavailable)?; + + // The name, if telemetry has resolved one, through exactly the path the + // leaderboard uses — so an account page and a standings row cannot + // disagree about who someone is. Only a real name: `attribute` falls back + // to the abbreviated preimage, which on a page that already shows the + // address in full would be noise dressed as an identity. + let display = miner.as_ref().and_then(|m| { + let held = runtime.attribute(m); + match held.source { + blackbeard_entities::AttributionSource::Preimage => None, + _ => Some(held.display), + } + }); + + Ok(Json(AccountDetail { + chain: id, + // Re-encoded rather than echoed: the answer is about the account, and + // returning the caller's spelling of it would let two spellings of one + // address look like two accounts. + address: blackbeard_core::wormhole::ss58_of(&account).unwrap_or(address), + account, + miner, + display, + rewards: RewardSummary { + count: totals.count, + total: BigUintDec(totals.total), + first_height: totals.first_height, + last_height: totals.last_height, + first_at: totals.first_at, + last_at: totals.last_at, + }, + activity: activity + .into_iter() + .map(|e| AccountEvent { + height: e.height, + event_index: e.event_index, + pallet: e.pallet, + variant: e.variant, + fields: e.fields, + at: e.at, + addresses: e + .accounts + .into_iter() + .filter_map(|hex| { + let address = blackbeard_core::wormhole::ss58_of(&hex)?; + Some((hex, address)) + }) + .collect(), + }) + .collect(), + indexed_from: scan.map(|(low, _)| low), + indexed_to: scan.map(|(_, high)| high), + })) +} + +/// An SS58 address for this network, as the raw account id. +/// +/// Validated here rather than passed through, for the same reason a preimage +/// is: a typo would otherwise be answered with an empty history, which reads +/// exactly like a real account that has never been paid. The checksum and the +/// network prefix must both hold — a Polkadot address is the same thirty-two +/// bytes wearing a different network, and answering for it would show someone +/// a page of activity that is not theirs. +fn parse_address(raw: &str) -> Result { + blackbeard_core::wormhole::account_id(raw).ok_or_else(|| { + Failure( + StatusCode::BAD_REQUEST, + ApiError::new( + "malformed_address", + format!("`{raw}` is not a Quantus address"), + ), + ) + }) +} + /// A reward preimage is 32 bytes of hex. /// /// Validated here rather than passed through, so a typo answers "that is not a diff --git a/crates/blackbeard-core/src/runtime.rs b/crates/blackbeard-core/src/runtime.rs index d372cb4..e65a877 100644 --- a/crates/blackbeard-core/src/runtime.rs +++ b/crates/blackbeard-core/src/runtime.rs @@ -29,7 +29,7 @@ //! `blackbeard-data` caches each blob by `spec_version` — one fetch per runtime //! version, ever, and decoding stays possible after the node has pruned. -use std::collections::BTreeMap; +use std::collections::{BTreeMap, BTreeSet}; use frame_metadata::v14::RuntimeMetadataV14; use frame_metadata::{RuntimeMetadata, RuntimeMetadataPrefixed}; @@ -72,6 +72,15 @@ pub struct DecodedEvent { pub extrinsic_index: Option, /// Fields, by name, normalised for storage — see [`normalise`]. pub fields: serde_json::Value, + /// Every account id this event mentions, as `0x` hex, deduplicated. + /// + /// Collected while decoding rather than scavenged from `fields` afterwards, + /// because by then an account and a block hash are both sixty-six + /// characters of hex and nothing distinguishes them. It is what makes + /// "everything involving this account" a query that works for event types + /// nobody has thought of yet: the field could be called `who`, `payee` or + /// `dest` and it lands here regardless. + pub accounts: Vec, } /// A runtime's description of itself, ready to decode with. @@ -181,7 +190,8 @@ impl Runtime { let mut out = Vec::with_capacity(records.len()); for (index, record) in records.into_iter().enumerate() { - let Some(event) = self.event_of(&record) else { + let mut accounts = BTreeSet::new(); + let Some(event) = self.event_of(&record, &mut accounts) else { continue; }; let (phase, extrinsic_index) = phase_of(&record); @@ -192,6 +202,7 @@ impl Runtime { phase, extrinsic_index, fields: event.2, + accounts: accounts.into_iter().collect(), }); } Ok(out) @@ -201,6 +212,7 @@ impl Runtime { fn event_of( &self, record: &scale_value::Value, + accounts: &mut BTreeSet, ) -> Option<(String, String, serde_json::Value)> { let event = field(record, "event")?; // RuntimeEvent is an enum of pallets; each pallet's is an enum of its @@ -218,10 +230,13 @@ impl Runtime { Some(( pallet.name.clone(), variant.name.clone(), - self.normalise(&scale_value::Value { - value: scale_value::ValueDef::Composite(variant.values.clone()), - context: inner.context, - }), + self.normalise( + &scale_value::Value { + value: scale_value::ValueDef::Composite(variant.values.clone()), + context: inner.context, + }, + accounts, + ), )) } @@ -238,20 +253,26 @@ impl Runtime { /// chain are `u128` and routinely past it, and `serde_json` would put /// them on the wire as JSON numbers for a browser to silently round — /// the same trap `BigUintDec` exists to avoid for difficulty. - fn normalise(&self, value: &scale_value::Value) -> serde_json::Value { + fn normalise( + &self, + value: &scale_value::Value, + accounts: &mut BTreeSet, + ) -> serde_json::Value { use scale_value::{Composite, Primitive, ValueDef}; match &value.value { ValueDef::Composite(c) => { if self.account_tys.contains_key(&value.context) && let Some(bytes) = as_bytes(c) { - return serde_json::Value::String(format!("0x{}", hex::encode(bytes))); + let hex = format!("0x{}", hex::encode(bytes)); + accounts.insert(hex.clone()); + return serde_json::Value::String(hex); } match c { Composite::Named(fields) => serde_json::Value::Object( fields .iter() - .map(|(k, v)| (k.clone(), self.normalise(v))) + .map(|(k, v)| (k.clone(), self.normalise(v, accounts))) .collect(), ), Composite::Unnamed(items) => { @@ -259,12 +280,12 @@ impl Runtime { // no information; unwrap it so `{"reward": 300}` does // not become `{"reward": [300]}`. if items.len() == 1 { - self.normalise(&items[0]) + self.normalise(&items[0], accounts) } else if let Some(bytes) = as_bytes(c) { serde_json::Value::String(format!("0x{}", hex::encode(bytes))) } else { serde_json::Value::Array( - items.iter().map(|v| self.normalise(v)).collect(), + items.iter().map(|v| self.normalise(v, accounts)).collect(), ) } } @@ -281,7 +302,7 @@ impl Runtime { v.name.clone(): self.normalise(&scale_value::Value { value: ValueDef::Composite(v.values.clone()), context: value.context, - }) + }, accounts) }) } ValueDef::BitSequence(bits) => { @@ -438,6 +459,43 @@ mod tests { assert!(reward.fields["reward"].is_number() || reward.fields["reward"].is_string()); } + /// The account list is what an account page is built on, and it must be + /// collected without the decoder knowing what a reward is: the field here + /// is called `miner`, a transfer's are `from` and `to`, and a pallet added + /// next year will call its own something else again. + #[test] + fn an_event_carries_the_accounts_it_mentions() { + let rt = Runtime::from_metadata(&metadata()).expect("parses"); + let blob = hex::decode( + include_str!("../tests/mainnet-events.hex") + .trim() + .trim_start_matches("0x"), + ) + .expect("fixture is hex"); + let events = rt.decode_events(&blob).expect("decodes"); + + let reward = events + .iter() + .find(|e| e.variant == "MinerRewarded") + .expect("the fixture block paid its author"); + assert_eq!( + reward.accounts, + vec![reward.fields["miner"].as_str().unwrap()] + ); + + // A block hash is also thirty-two bytes. Nothing that is not an + // `AccountId32` in the registry may end up here, or an account page + // would answer to a hash. + for event in &events { + for account in &event.accounts { + assert!( + account.starts_with("0x") && account.len() == 66, + "{account}" + ); + } + } + } + #[test] fn a_block_decoded_against_the_wrong_runtime_fails_loudly() { // Trailing bytes mean the registry and the data disagree. Storing a diff --git a/crates/blackbeard-core/src/wormhole.rs b/crates/blackbeard-core/src/wormhole.rs index 3bcf963..c1c0f7e 100644 --- a/crates/blackbeard-core/src/wormhole.rs +++ b/crates/blackbeard-core/src/wormhole.rs @@ -141,6 +141,19 @@ pub fn account_id(address: &str) -> Option { Some(format!("0x{}", hex::encode(&raw[2..34]))) } +/// SS58-encode a `0x` hex account id for this network. The inverse of +/// [`account_id`], used to give one canonical spelling back to a caller who may +/// have sent another. +pub fn ss58_of(account_hex: &str) -> Option { + let mut account = [0u8; 32]; + hex::decode_to_slice( + account_hex.strip_prefix("0x").unwrap_or(account_hex), + &mut account, + ) + .ok()?; + Some(ss58(&account, SS58_PREFIX)) +} + /// Base58 decode: the inverse of [`base58`], and equally little arithmetic. fn base58_decode(input: &str) -> Option> { let mut bytes: Vec = Vec::with_capacity(input.len()); diff --git a/crates/blackbeard-data/migrations/0005_event_accounts.sql b/crates/blackbeard-data/migrations/0005_event_accounts.sql new file mode 100644 index 0000000..ef99763 --- /dev/null +++ b/crates/blackbeard-data/migrations/0005_event_accounts.sql @@ -0,0 +1,38 @@ +-- Which accounts an event is about. +-- +-- ## Why a column rather than three `fields @> …` predicates +-- +-- "Everything involving this account" could be asked as a union over the field +-- names we happen to know — `miner`, `from`, `to` — and each would even use the +-- existing jsonb index. But that list is a guess about the runtime's +-- vocabulary, and the whole point of decoding against the runtime's own +-- metadata is not to keep such a list. A pallet added next year will name its +-- field `payee` or `who` or `dest`, and an account page built on guessed names +-- would answer "no activity" rather than fail. +-- +-- `blackbeard-core::runtime` already knows which values are accounts — it +-- identifies `AccountId32` by its registry path, which is also how it avoids +-- rendering a block hash as an address — so it collects them while decoding and +-- the column is filled from the decoder's own answer. Any event type, present +-- or future, joins an account page for free. +alter table chain_event add column accounts text[] not null default '{}'; + +-- `array_ops` containment: "rows whose accounts include this one". The same +-- shape as the jsonb index beside it, and the reason an account page does not +-- need a table per event type. +create index chain_event_accounts_idx on chain_event using gin (accounts); + +-- When the block said it was. +-- +-- The chain's own clock, from the block's `Timestamp::set`, not when this +-- observer saw anything. `block.authored_at` holds the same thing, but only for +-- the blocks this observer was running for — an account's rewards run back to +-- genesis, and a history that renders "height 412" with no date because the +-- process was not alive in March is not a history. +-- +-- Nullable because it is one more RPC call that a node may decline for a block +-- it has pruned, and a reward with no date is still a reward. +alter table chain_event add column at timestamptz; + +-- "This account's activity, newest first" reads the index in order and stops. +create index chain_event_account_recent_idx on chain_event (chain, height desc, event_index desc); diff --git a/crates/blackbeard-data/src/store.rs b/crates/blackbeard-data/src/store.rs index 9820399..0fd87ba 100644 --- a/crates/blackbeard-data/src/store.rs +++ b/crates/blackbeard-data/src/store.rs @@ -150,11 +150,20 @@ pub struct EventRecord { pub extrinsic_index: Option, /// Normalised fields. pub fields: serde_json::Value, + /// Every account the event mentions, as `0x` hex — the decoder's own + /// answer, not a guess from the field names. + pub accounts: Vec, + /// The block's own timestamp, when the node answered for it. + pub at: Option>, } /// A decoded event read back. #[derive(Debug, Clone)] pub struct StoredEvent { + /// The block's own timestamp, when the node answered for it. + pub at: Option>, + /// Every account the event mentions, as `0x` hex. + pub accounts: Vec, /// Block it fired in. pub height: u64, /// Position within that block's event list. @@ -171,6 +180,23 @@ pub struct StoredEvent { pub fields: serde_json::Value, } +/// Totals over an account's mining rewards. +#[derive(Debug, Clone)] +pub struct RewardTotals { + /// How many reward events this account has been the subject of. + pub count: u64, + /// Their sum, in the chain's smallest unit, as a decimal string. + pub total: String, + /// Height of the first, and of the last. + pub first_height: Option, + /// Height of the most recent. + pub last_height: Option, + /// When the first was, and the last. + pub first_at: Option>, + /// When the most recent was. + pub last_at: Option>, +} + /// A held attribution loaded back from the database. #[derive(Debug, Clone)] pub struct StoredAttribution { @@ -834,21 +860,38 @@ impl Store { .map(|e| e.extrinsic_index.map(|i| i as i32)) .collect(); let fields: Vec = events.iter().map(|e| e.fields.clone()).collect(); + // `unnest` cannot yield an array-valued column, so the account lists + // travel as JSON arrays and are unpacked per row on arrival. + let accounts: Vec = events + .iter() + .map(|e| serde_json::Value::from(e.accounts.clone())) + .collect(); + let times: Vec>> = events.iter().map(|e| e.at).collect(); let result = sqlx::query!( r#" insert into chain_event - (chain, height, event_index, pallet, variant, phase, extrinsic_index, fields) - select * from unnest( + (chain, height, event_index, pallet, variant, phase, extrinsic_index, + fields, accounts, at) + select chain, height, event_index, pallet, variant, phase, extrinsic_index, + fields, array(select jsonb_array_elements_text(accounts)), at + from unnest( $1::text[], $2::bigint[], $3::int[], $4::text[], - $5::text[], $6::text[], $7::int[], $8::jsonb[] - ) + $5::text[], $6::text[], $7::int[], $8::jsonb[], $9::jsonb[], + $10::timestamptz[] + ) as t(chain, height, event_index, pallet, variant, phase, extrinsic_index, + fields, accounts, at) on conflict (chain, height, event_index) do update set pallet = excluded.pallet, variant = excluded.variant, phase = excluded.phase, extrinsic_index = excluded.extrinsic_index, - fields = excluded.fields + fields = excluded.fields, + accounts = excluded.accounts, + -- Never overwrite a time we have with one we do not: a + -- re-index against a node that has since pruned would blank + -- the history it was meant to confirm. + at = coalesce(excluded.at, chain_event.at) "#, &chains, &heights, @@ -858,6 +901,8 @@ impl Store { &phases, &extrinsics as &[Option], &fields, + &accounts, + × as &[Option>], ) .execute(&self.pool) .await?; @@ -908,35 +953,44 @@ impl Store { Ok(()) } - /// Events of one kind involving one account, newest first. + /// Everything involving one account, newest first. /// - /// The generic query behind every per-account view. `fields @> …` is - /// answered by the `jsonb_path_ops` GIN index, so rewards, transfers and - /// whatever the chain grows next are all this one method with different - /// arguments — no table and no query per event type. - pub async fn events_for_account( + /// The whole per-account view, in one query, for every event type the chain + /// has or will have. `accounts @> array[…]` is answered by the GIN index, + /// and the list it searches is the decoder's own — so a pallet added next + /// year appears here without a migration, a struct or a query. + /// + /// `before` pages backwards: pass the `(height, event_index)` of the last + /// row seen. Keyset rather than `offset`, because new blocks arrive at the + /// front of this ordering while a reader is paging through it and `offset` + /// would show them the same row twice. + pub async fn account_events( &self, chain: &ChainId, - pallet: &str, - variant: &str, - field: &str, account_hex: &str, + before: Option<(u64, u32)>, limit: i64, ) -> Result, DataError> { - let filter = serde_json::json!({ field: account_hex }); + let (before_height, before_index) = match before { + Some((h, i)) => (h as i64, i as i32), + // The tuple comparison below is inclusive of everything under this, + // which for the first page is everything. + None => (i64::MAX, i32::MAX), + }; let rows = sqlx::query!( r#" select height, event_index, pallet, variant, phase, extrinsic_index, - fields as "fields!" + fields as "fields!", at, accounts as "accounts!" from chain_event - where chain = $1 and pallet = $2 and variant = $3 and fields @> $4 + where chain = $1 and accounts @> array[$2] + and (height, event_index) < ($3, $4) order by height desc, event_index desc limit $5 "#, chain.as_str(), - pallet, - variant, - filter, + account_hex, + before_height, + before_index, limit, ) .fetch_all(&self.pool) @@ -951,10 +1005,81 @@ impl Store { phase: r.phase, extrinsic_index: r.extrinsic_index.map(|i| i.max(0) as u32), fields: r.fields, + at: r.at, + accounts: r.accounts, }) .collect()) } + /// What an account has been paid for mining, over the whole indexed record. + /// + /// Returned as a decimal string: rewards are `u128` planck and a run of + /// them passes what any integer type here holds, let alone what JSON would + /// carry without rounding. `numeric` does the addition exactly and the + /// string crosses every boundary intact, the same trade `BigUintDec` makes + /// for difficulty. + pub async fn account_rewards( + &self, + chain: &ChainId, + account_hex: &str, + ) -> Result { + let row = sqlx::query!( + r#" + select count(*) as "count!", + coalesce(sum((fields->>'reward')::numeric), 0)::text as "total!", + min(height) as first_height, + max(height) as last_height, + min(at) as first_at, + max(at) as last_at + from chain_event + where chain = $1 and accounts @> array[$2] + and pallet = 'MiningRewards' and variant = 'MinerRewarded' + "#, + chain.as_str(), + account_hex, + ) + .fetch_one(&self.pool) + .await?; + Ok(RewardTotals { + count: row.count.max(0) as u64, + total: row.total, + first_height: row.first_height.map(|h| h.max(0) as u64), + last_height: row.last_height.map(|h| h.max(0) as u64), + first_at: row.first_at, + last_at: row.last_at, + }) + } + + /// The reward preimage behind an address, if the observer watched it win. + /// + /// The derivation runs one way — a preimage gives an address and nothing + /// gives the preimage back — so this is a lookup rather than a calculation, + /// and it is done by joining a reward event to the block it fired in rather + /// than by hashing every preimage ever seen. `None` means only that this + /// observer was not running for any block this account was paid for. + pub async fn miner_for_account( + &self, + chain: &ChainId, + account_hex: &str, + ) -> Result, DataError> { + let row = sqlx::query!( + r#" + select b.miner + from chain_event e + join block b on b.chain = e.chain and b.height = e.height + where e.chain = $1 and e.accounts @> array[$2] + and e.pallet = 'MiningRewards' and e.variant = 'MinerRewarded' + order by e.height desc + limit 1 + "#, + chain.as_str(), + account_hex, + ) + .fetch_optional(&self.pool) + .await?; + Ok(row.map(|r| MinerId(r.miner))) + } + /// Persist the attributions currently held. pub async fn save_attributions( &self, diff --git a/crates/blackbeard-entities/Cargo.toml b/crates/blackbeard-entities/Cargo.toml index 4211b34..17a115a 100644 --- a/crates/blackbeard-entities/Cargo.toml +++ b/crates/blackbeard-entities/Cargo.toml @@ -11,6 +11,7 @@ repository.workspace = true [dependencies] chrono.workspace = true serde.workspace = true +serde_json.workspace = true thiserror.workspace = true ts-rs.workspace = true diff --git a/crates/blackbeard-entities/src/account.rs b/crates/blackbeard-entities/src/account.rs new file mode 100644 index 0000000..26e23e8 --- /dev/null +++ b/crates/blackbeard-entities/src/account.rs @@ -0,0 +1,114 @@ +//! One account, and what the chain says happened to it. +//! +//! An account is addressed by the SS58 string a miner recognises, because that +//! is what their pool configuration and their wallet show. Everything stored is +//! keyed on the raw account id, so the API converts once at the edge — a +//! mistyped address is then rejected as malformed rather than answered with an +//! empty history, which reads identically to a real account that has done +//! nothing. + +use std::collections::BTreeMap; + +use chrono::{DateTime, Utc}; +use serde::{Deserialize, Serialize}; +use ts_rs::TS; + +use crate::{BigUintDec, ChainId, MinerId}; + +/// Everything the observer holds about one account. +#[derive(Debug, Clone, Serialize, Deserialize, TS)] +#[ts(export, export_to = "AccountDetail.ts")] +pub struct AccountDetail { + /// Which chain. + pub chain: ChainId, + /// The address as asked for, re-encoded canonically. + pub address: String, + /// The raw account id, `0x` hex — what the events are keyed on. + pub account: String, + /// The reward preimage this address derives from, when a block the observer + /// recorded was authored by it. + /// + /// The derivation runs one way only: a preimage gives an address, and no + /// amount of arithmetic gives the preimage back. So this is a *lookup* + /// among preimages already seen, and its absence means only that this + /// observer has not watched this account win a block — not that it never + /// has. + pub miner: Option, + /// The telemetry name held for that miner, if one is. + pub display: Option, + /// Mining rewards, over the whole indexed record. + pub rewards: RewardSummary, + /// Everything involving this account, newest first. + pub activity: Vec, + /// The lowest and highest block whose events have been read for this chain. + /// + /// Reported because it is the honest scope of every number above: an + /// account page is a claim about a range of history, and a backfill still + /// working its way toward genesis has not made that claim yet. + #[ts(type = "number")] + pub indexed_from: Option, + /// The highest block whose events have been read. + #[ts(type = "number")] + pub indexed_to: Option, +} + +/// What an account has been paid for mining. +#[derive(Debug, Clone, Serialize, Deserialize, TS)] +#[ts(export, export_to = "RewardSummary.ts")] +pub struct RewardSummary { + /// How many blocks it was paid for. + #[ts(type = "number")] + pub count: u64, + /// Their sum, in the chain's smallest unit. A decimal string for the same + /// reason difficulty is: these are `u128` and a JSON number would round. + pub total: BigUintDec, + /// Height of the first reward in the indexed record. + #[ts(type = "number")] + pub first_height: Option, + /// Height of the most recent. + #[ts(type = "number")] + pub last_height: Option, + /// When the first was, by the chain's own clock. + pub first_at: Option>, + /// When the most recent was. + pub last_at: Option>, +} + +/// One thing that happened to an account. +/// +/// Deliberately not a closed set of kinds. The runtime names its own events and +/// the decoder keeps those names, so a pallet added next year appears here as +/// itself rather than as "unknown" — which is the whole reason the index is one +/// table rather than one per thing the site happens to show today. +#[derive(Debug, Clone, Serialize, Deserialize, TS)] +#[ts(export, export_to = "AccountEvent.ts")] +pub struct AccountEvent { + /// Block it fired in. + #[ts(type = "number")] + pub height: u64, + /// Position within that block's events, which with the height is its + /// identity and what pages the list. + #[ts(type = "number")] + pub event_index: u32, + /// Emitting pallet, as the runtime names it. + pub pallet: String, + /// Event variant, as the runtime names it. + pub variant: String, + /// The fields, as the runtime names them. Accounts are `0x` hex and any + /// integer past 2^53 is a string. + #[ts(type = "Record")] + pub fields: serde_json::Value, + /// The block's own timestamp, when the node answered for it. + pub at: Option>, + /// Every account the event mentions, as `0x hex → SS58 address`. + /// + /// A companion to [`Self::fields`] rather than a substitution inside it: + /// the fields stay exactly what the runtime said, and this is the same + /// values in the spelling a person recognises. Doing it here rather than in + /// the browser is also the only place it can be done — SS58 is a blake2b + /// checksum over a base58 encoding, and shipping that to the frontend to + /// render a counterparty would be a second implementation to keep in step + /// with the first. + #[ts(type = "Record")] + pub addresses: BTreeMap, +} diff --git a/crates/blackbeard-entities/src/lib.rs b/crates/blackbeard-entities/src/lib.rs index f7e1863..7d55ba9 100644 --- a/crates/blackbeard-entities/src/lib.rs +++ b/crates/blackbeard-entities/src/lib.rs @@ -15,6 +15,7 @@ #![deny(missing_docs)] +mod account; mod block; mod chain; mod error; @@ -22,6 +23,7 @@ mod miner; mod series; mod ws; +pub use account::{AccountDetail, AccountEvent, RewardSummary}; pub use block::{BlockDetail, BlockObservation, RecentBlock}; pub use chain::{ChainId, ChainInfo, ChainStatus, ChainSummary, ClientVersion, Tracking}; pub use error::{ApiError, EntityError}; diff --git a/readme.md b/readme.md index d7df6a1..466cf41 100644 --- a/readme.md +++ b/readme.md @@ -150,6 +150,30 @@ the tip — and what it has since forgotten, the difficulty recorded while the state still existed. Anything neither can answer says so in words rather than going blank, because a gap on a block page reads as a zero. +## One account, from our own index + +`/quantus/account/qzp2AxZw…` answers what the official explorer does not: what +an address has actually been paid, every reward, back as far as the index has +read. The address is converted to a raw account id at the edge, so a typo is +rejected as malformed rather than answered with an empty history — which reads +exactly like a real account that has never been paid — and a Polkadot address is +rejected too: same thirty-two bytes, different network, and answering for it +would show someone activity that is not theirs. + +The activity table has no case per event type. Every `chain_event` row carries +the accounts it mentions in a column the *decoder* filled — it knows which +values are `AccountId32` by their registry path, which is also how it avoids +rendering a block hash as an address — so `accounts @> array[…]` finds +everything, including from pallets that do not exist yet. The frontend labels +and formats what it recognises and shows anything else as its own key and value, +so a new event type appears as itself rather than not at all. + +The preimage and the address are the two ends of one identity, and each page +links to the other: the miner page counts blocks, the account page counts +tokens, and the derivation joins them. Going the other way — address to preimage +— is a lookup among preimages already seen, not a calculation, because the +Poseidon2 derivation runs one way only. + ## Every view has an address Paths, not a hash: `/quantus/day`, `/quantus/block/13160`, diff --git a/web/src/App.tsx b/web/src/App.tsx index aaca5be..04bb0a5 100644 --- a/web/src/App.tsx +++ b/web/src/App.tsx @@ -10,6 +10,7 @@ import { useCallback, useEffect, useMemo } from 'react' import { Link, useLocation, useNavigate } from 'react-router-dom' +import { AccountPanel } from './components/AccountPanel' import { BlockPanel } from './components/BlockPanel' import { BlockTicker } from './components/BlockTicker' import { ChainSwitcher } from './components/ChainSwitcher' @@ -146,6 +147,19 @@ export default function App() { /> )} + {route.account && chain && ( + + )} + {route.miner && chain && ( , +/** + * The lowest and highest block whose events have been read for this chain. + * + * Reported because it is the honest scope of every number above: an + * account page is a claim about a range of history, and a backfill still + * working its way toward genesis has not made that claim yet. + */ +indexed_from: number, +/** + * The highest block whose events have been read. + */ +indexed_to: number, }; diff --git a/web/src/api/generated/AccountEvent.ts b/web/src/api/generated/AccountEvent.ts new file mode 100644 index 0000000..b44bc38 --- /dev/null +++ b/web/src/api/generated/AccountEvent.ts @@ -0,0 +1,49 @@ +// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually. + +/** + * One thing that happened to an account. + * + * Deliberately not a closed set of kinds. The runtime names its own events and + * the decoder keeps those names, so a pallet added next year appears here as + * itself rather than as "unknown" — which is the whole reason the index is one + * table rather than one per thing the site happens to show today. + */ +export type AccountEvent = { +/** + * Block it fired in. + */ +height: number, +/** + * Position within that block's events, which with the height is its + * identity and what pages the list. + */ +event_index: number, +/** + * Emitting pallet, as the runtime names it. + */ +pallet: string, +/** + * Event variant, as the runtime names it. + */ +variant: string, +/** + * The fields, as the runtime names them. Accounts are `0x` hex and any + * integer past 2^53 is a string. + */ +fields: Record, +/** + * The block's own timestamp, when the node answered for it. + */ +at: string | null, +/** + * Every account the event mentions, as `0x hex → SS58 address`. + * + * A companion to [`Self::fields`] rather than a substitution inside it: + * the fields stay exactly what the runtime said, and this is the same + * values in the spelling a person recognises. Doing it here rather than in + * the browser is also the only place it can be done — SS58 is a blake2b + * checksum over a base58 encoding, and shipping that to the frontend to + * render a counterparty would be a second implementation to keep in step + * with the first. + */ +addresses: Record, }; diff --git a/web/src/api/generated/RewardSummary.ts b/web/src/api/generated/RewardSummary.ts new file mode 100644 index 0000000..fe4cdf8 --- /dev/null +++ b/web/src/api/generated/RewardSummary.ts @@ -0,0 +1,32 @@ +// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually. +import type { BigUintDec } from "./BigUintDec"; + +/** + * What an account has been paid for mining. + */ +export type RewardSummary = { +/** + * How many blocks it was paid for. + */ +count: number, +/** + * Their sum, in the chain's smallest unit. A decimal string for the same + * reason difficulty is: these are `u128` and a JSON number would round. + */ +total: BigUintDec, +/** + * Height of the first reward in the indexed record. + */ +first_height: number, +/** + * Height of the most recent. + */ +last_height: number, +/** + * When the first was, by the chain's own clock. + */ +first_at: string | null, +/** + * When the most recent was. + */ +last_at: string | null, }; diff --git a/web/src/api/rest.ts b/web/src/api/rest.ts index adf312a..6682037 100644 --- a/web/src/api/rest.ts +++ b/web/src/api/rest.ts @@ -6,6 +6,7 @@ * Pushing it to every connected tab would be strictly worse. */ +import type { AccountDetail } from './generated/AccountDetail' import type { ApiError } from './generated/ApiError' import type { BlockDetail } from './generated/BlockDetail' import type { ChainSeries } from './generated/ChainSeries' @@ -78,6 +79,27 @@ export function fetchBlock( ) } +/** + * One account: what it was paid, and everything else it appears in. + * + * Paged with a keyset rather than an offset — pass the `(height, event_index)` + * of the last row already shown. New blocks arrive at the front of this + * ordering while a reader is paging through it, and an offset would show them + * the same row twice. + */ +export function fetchAccount( + chain: string, + address: string, + before?: { height: number; index: number }, + signal?: AbortSignal, +): Promise { + const page = before ? `?before_height=${before.height}&before_index=${before.index}` : '' + return get( + `/chains/${encodeURIComponent(chain)}/accounts/${encodeURIComponent(address)}${page}`, + signal, + ) +} + /** One miner's standing and history. */ export function fetchMiner( chain: string, diff --git a/web/src/components/AccountPanel.tsx b/web/src/components/AccountPanel.tsx new file mode 100644 index 0000000..48401d7 --- /dev/null +++ b/web/src/components/AccountPanel.tsx @@ -0,0 +1,329 @@ +/** + * One account's page. + * + * The thing the official explorer does badly: what an address has actually been + * paid, in full, back as far as the observer has read. Everything here comes + * from this observer's own index — events decoded against the runtime that + * produced each block — so it does not depend on any external indexer and does + * not stop working when the node prunes the state behind it. + * + * The activity table renders whatever the runtime emitted, under the runtime's + * own names. `LABELS` and `AMOUNTS` below are presentation only: a field they + * do not know still appears, as its key and its value, rather than vanishing. + * That is the difference between a page that shows what happened and one that + * shows the subset somebody remembered to write a case for. + */ + +import { useEffect, useState } from 'react' +import { Link } from 'react-router-dom' + +import type { AccountDetail } from '../api/generated/AccountDetail' +import type { AccountEvent } from '../api/generated/AccountEvent' +import { RequestFailed, fetchAccount } from '../api/rest' +import { exactTokens, height as fmtHeight, shortAddress, tokens, when } from '../lib/format' +import { href } from '../lib/routes' + +/** Field names that carry a balance, and so want the token treatment. */ +const AMOUNTS = new Set(['reward', 'amount', 'value', 'fee', 'actual_fee', 'tip']) + +/** Human labels for the events the site sees most. Anything else uses its own + * `Pallet::Variant`, which is already the runtime's answer and not a guess. */ +const LABELS: Record = { + 'MiningRewards::MinerRewarded': 'Mining reward', + 'MiningRewards::FeesCollected': 'Fees collected', + 'Balances::Transfer': 'Transfer', +} + +function label(event: AccountEvent): string { + return LABELS[`${event.pallet}::${event.variant}`] ?? `${event.pallet}::${event.variant}` +} + +/** A 32-byte account id, which is what the decoder renders accounts as. */ +function isAccount(value: unknown): value is string { + return typeof value === 'string' && /^0x[0-9a-f]{64}$/.test(value) +} + +/** + * One event's fields, in the runtime's own vocabulary. + * + * The account this page is about is folded away: every row here involves it by + * definition, and repeating it in every row would bury the half that differs. + */ +function Fields({ + event, + account, + chain, + decimals, + symbol, +}: { + event: AccountEvent + account: string + chain: string + decimals: number + symbol: string +}) { + const shown = Object.entries(event.fields as Record).filter( + ([, value]) => !(isAccount(value) && value === account), + ) + return ( + + {shown.map(([key, value]) => ( + + {/* The key only when there is something to tell apart. A reward has + one field left once this account is folded out of it, and + "REWARD 0.31 QTC" in a column headed Detail says the same thing + twice. */} + {shown.length > 1 && {key}} + + + ))} + + ) +} + +function Value({ + name, + value, + chain, + addresses, + decimals, + symbol, +}: { + name: string + value: unknown + chain: string + addresses: Record + decimals: number + symbol: string +}) { + if (AMOUNTS.has(name) && (typeof value === 'string' || typeof value === 'number')) { + const raw = String(value) + return ( + + {tokens(raw, decimals)} {symbol} + + ) + } + if (isAccount(value)) { + // The counterparty, in the spelling they would recognise and as a way to + // their own page. The raw id is kept in the title, because it is what the + // chain actually stored and what anyone checking our working needs. + const address = addresses[value] + if (!address) { + return ( + + {shortAddress(value)} + + ) + } + return ( + + {shortAddress(address)} + + ) + } + // Anything the cases above do not know. Shown rather than dropped: the index + // holds every field the runtime emitted, and a page that hides the ones it + // has no styling for is lying by omission. + return ( + + {typeof value === 'object' ? JSON.stringify(value) : String(value)} + + ) +} + +export function AccountPanel({ + chain, + address, + decimals, + symbol, + onClose, +}: { + chain: string + address: string + /** The chain's token decimals; 12 on Quantus, but read rather than assumed. */ + decimals: number + symbol: string + onClose: () => void +}) { + const [detail, setDetail] = useState(null) + const [error, setError] = useState(null) + + useEffect(() => { + const controller = new AbortController() + setDetail(null) + setError(null) + fetchAccount(chain, address, undefined, controller.signal) + .then(setDetail) + .catch((e: unknown) => { + // An abort is this component being replaced, not a failure to report. + if (controller.signal.aborted) return + setError(e instanceof RequestFailed ? e.message : 'Could not reach the observer.') + }) + return () => controller.abort() + }, [chain, address]) + + return ( +
+
+
+
Account
+ {/* An address is case-sensitive — SS58's checksum is over the exact + bytes and the base58 alphabet uses both cases — so the panel + title's uppercase is switched off when the title *is* one. A name + keeps it. */} +

+ {detail?.display ?? shortAddress(detail?.address ?? address)} +

+
+
Address
+
{detail?.address ?? address}
+ {detail?.miner && ( + <> + {/* The preimage is the identity the chain itself asserts, and + the one the standings are keyed on — so this is the way back + to the miner's own page from the address they recognise. */} +
Preimage
+
+ {detail.miner} +
+ + )} +
+
+ +
+ + {error &&

{error}

} + {!error && !detail &&

Reading the record…

} + + {detail && ( + <> + {/* Only for an account that has actually been paid. Four tiles + reading 0, 0, — and — is not a summary of anything; it is the + mining shape of this page imposed on an account that has never + mined, and it pushes the history that does exist below the fold. */} + {detail.rewards.count > 0 && ( +
+
+
Mined
+
+ {tokens(detail.rewards.total, decimals, 2)} +
+
{symbol} in rewards
+
+
+
Blocks paid
+
{fmtHeight(detail.rewards.count)}
+
reward events
+
+
+
First paid
+
+ {detail.rewards.first_height ? `#${fmtHeight(detail.rewards.first_height)}` : '—'} +
+
{when(detail.rewards.first_at)}
+
+
+
Last paid
+
+ {detail.rewards.last_height ? `#${fmtHeight(detail.rewards.last_height)}` : '—'} +
+
{when(detail.rewards.last_at)}
+
+
+ )} + + {detail.activity.length === 0 ? ( +

+ Nothing in the indexed record involves this account. It is a valid Quantus address — + the checksum holds — but the observer has seen nothing happen to it. +

+ ) : ( +
+ + + + + + + + + + + + {detail.activity.map((event) => ( + + + + + + + ))} + +
+ Everything the chain recorded involving this account, newest first +
Block + Event + + Detail + + When +
+ + #{fmtHeight(event.height)} + + {label(event)} + + + {when(event.at)} +
+
+ )} + + {/* The scope of every number above. An account page is a claim about + a range of history, and a backfill still working toward genesis + has not made that claim yet — saying so is the difference between + "nothing before block 8,075" and "nothing, as far as we looked". */} +

+ Read from the chain's own events, decoded against the runtime that produced each block. + {detail.indexed_from !== null && detail.indexed_to !== null && ( + <> + {' '} + The observer has read blocks {fmtHeight(detail.indexed_from)} to{' '} + {fmtHeight(detail.indexed_to)} + {detail.indexed_from > 1 && ' and is still working back toward genesis'}. + + )} + {detail.activity.length >= 100 && ' Showing the most recent 100 events.'} +

+ + )} +
+ ) +} diff --git a/web/src/components/MinerPanel.tsx b/web/src/components/MinerPanel.tsx index 8124183..86fb8dc 100644 --- a/web/src/components/MinerPanel.tsx +++ b/web/src/components/MinerPanel.tsx @@ -8,11 +8,13 @@ */ import { useEffect, useState } from 'react' +import { Link } from 'react-router-dom' import type { MinerDetail } from '../api/generated/MinerDetail' import type { Window as WindowName } from '../api/generated/Window' import { RequestFailed, fetchMiner } from '../api/rest' import { ago, bigNumber, hashrate, height, share, shortMiner } from '../lib/format' +import { href } from '../lib/routes' import { usePinnedMiners } from '../lib/store' import { ShareChart } from './ShareChart' @@ -76,7 +78,12 @@ export function MinerPanel({ {detail?.address && ( <>
Rewards
-
{detail.address}
+
+ {/* The way through to what was actually paid: this page + counts blocks, the account page counts tokens, and the + address is the only thing that joins them. */} + {detail.address} +
)}
Preimage
diff --git a/web/src/index.css b/web/src/index.css index 71f8e0c..dd7887d 100644 --- a/web/src/index.css +++ b/web/src/index.css @@ -989,3 +989,66 @@ tr.mine .share-bar > i { white-space: nowrap; border: 0; } + +/* ---- account activity ---------------------------------------------------- */ + +/* The buttons in a panel head. Written out once here rather than inline on each + one: they were four copies of the same eight declarations, and a fifth was + about to be a fifth copy. */ +.panel-button { + padding: 7px 13px; + font: inherit; + font-size: 12px; + letter-spacing: 0.1em; + text-transform: uppercase; + color: var(--text-secondary); + cursor: pointer; +} + +/* One event's fields on one line. They are read left to right as a phrase — + "0.31 QUAN", "to qzp2AxZw…rs8L" — so they flow rather than tabulate: the + fields differ per event type and a column per possible field would be mostly + empty. */ +.event-fields { + display: inline-flex; + flex-wrap: wrap; + align-items: baseline; + gap: 4px 10px; +} + +.event-field { + display: inline-flex; + align-items: baseline; + gap: 5px; +} + +.event-key { + color: var(--text-muted); + font-size: 10px; + letter-spacing: 0.08em; + text-transform: uppercase; +} + +/* Deliberately not `.last-seen`, which the leaderboard drops below 1320px. On + a payment history the date is the second thing anyone reads after the amount; + it only goes on a phone, where the table scrolls anyway. */ +.event-when { + white-space: nowrap; +} + +@media (max-width: 640px) { + .board .event-when { + display: none; + } +} + +/* The caveat under a panel, in the same register as the page footer: what the + numbers above are, and what they are not. */ +.panel-note { + margin: 0; + padding: 12px 16px; + border-top: var(--rule); + color: var(--text-muted); + font-size: 11px; + line-height: 1.6; +} diff --git a/web/src/lib/format.ts b/web/src/lib/format.ts index b6601b3..8f7c272 100644 --- a/web/src/lib/format.ts +++ b/web/src/lib/format.ts @@ -92,3 +92,49 @@ export function windowSpan(blocks: number, intervalSeconds: number): string { if (total < 172800) return `~${Math.round(total / 3600)} h` return `~${Math.round(total / 86400)} d` } + +/** + * A balance in the chain's smallest unit, as a readable token amount. + * + * The value arrives as a decimal string because it is `u128` and a JSON number + * would round it, so the division is done on the digits rather than by parsing: + * `Number(…) / 1e12` is exact for the first fifteen digits and quietly wrong + * after that, which is a range this chain's cumulative rewards reach within + * weeks. + * + * Four decimal places, not twelve: a reward is 0.31 QUAN and the eight zeroes + * after it are noise. The `title` on the element carries the exact figure. + */ +export function tokens(raw: string | null | undefined, decimals: number, places = 4): string { + if (!raw) return '—' + const digits = raw.replace(/^0+(?=\d)/, '') + const padded = digits.padStart(decimals + 1, '0') + const whole = padded.slice(0, padded.length - decimals) + const fraction = padded.slice(padded.length - decimals) + const shown = fraction.slice(0, places).replace(/0+$/, '') + return `${BigInt(whole).toLocaleString('en-US')}${shown ? `.${shown}` : ''}` +} + +/** The exact amount, every decimal place, for a `title` attribute. */ +export function exactTokens(raw: string, decimals: number): string { + const padded = raw.replace(/^0+(?=\d)/, '').padStart(decimals + 1, '0') + const whole = padded.slice(0, padded.length - decimals) + return `${BigInt(whole).toString()}.${padded.slice(padded.length - decimals)}` +} + +/** An SS58 address short enough for a table cell, keeping both ends. */ +export function shortAddress(address: string): string { + return address.length > 14 ? `${address.slice(0, 8)}…${address.slice(-4)}` : address +} + +/** An absolute timestamp, for a history where "3 days ago" is not enough. */ +export function when(iso: string | null | undefined): string { + if (!iso) return '—' + return new Date(iso).toLocaleString('en-GB', { + year: 'numeric', + month: 'short', + day: '2-digit', + hour: '2-digit', + minute: '2-digit', + }) +}