4 Commits

Author SHA1 Message Date
Luke Parker
d219b77bd0 Add bindings to the events from the coins module to serai-client-serai 2025-11-15 16:13:25 -05:00
Luke Parker
fce26eaee1 Update the block RPCs to return null when missing, not an error
Promotes clarity.
2025-11-15 16:12:39 -05:00
Luke Parker
3cfbd9add7 Update serai-coordinator-cosign to the new serai-client-serai 2025-11-15 16:10:58 -05:00
Luke Parker
609cf06393 Update SetDecided to include the validators
Necessary for light-client protocols to follow along with consensus. Arguably,
anyone handling GRANDPA's consensus could peek at this through the consensus
commit anyways, but we shouldn't so defer that.
2025-11-15 14:59:33 -05:00
16 changed files with 218 additions and 62 deletions

View File

@@ -22,6 +22,7 @@ blake2 = { version = "0.11.0-rc.0", default-features = false, features = ["alloc
borsh = { version = "1", default-features = false, features = ["std", "derive", "de_strict_order"] }
serai-abi = { path = "../../substrate/abi", default-features = false, features = ["std"] }
serai-client-serai = { path = "../../substrate/client/serai", default-features = false }
log = { version = "0.4", default-features = false, features = ["std"] }

View File

@@ -1,10 +1,13 @@
use core::future::Future;
use std::{sync::Arc, collections::HashMap};
use blake2::{Digest, Blake2b256};
use serai_abi::primitives::{
balance::Amount, validator_sets::ExternalValidatorSet, address::SeraiAddress,
merkle::IncrementalUnbalancedMerkleTree,
};
use serai_client::Serai;
use serai_client_serai::Serai;
use serai_db::*;
use serai_task::ContinuallyRan;
@@ -14,6 +17,7 @@ use crate::*;
create_db!(
CosignIntend {
ScanCosignFrom: () -> u64,
BuildsUpon: () -> IncrementalUnbalancedMerkleTree,
}
);
@@ -40,9 +44,9 @@ async fn block_has_events_justifying_a_cosign(
.await
.map_err(|e| format!("{e:?}"))?
.ok_or_else(|| "couldn't get block which should've been finalized".to_string())?;
let serai = serai.as_of(block.hash());
let serai = serai.as_of(block.header.hash()).await.map_err(|e| format!("{e:?}"))?;
if !serai.validator_sets().key_gen_events().await.map_err(|e| format!("{e:?}"))?.is_empty() {
if !serai.validator_sets().set_keys_events().await.map_err(|e| format!("{e:?}"))?.is_empty() {
return Ok((block, HasEvents::Notable));
}
@@ -66,7 +70,7 @@ impl<D: Db> ContinuallyRan for CosignIntendTask<D> {
async move {
let start_block_number = ScanCosignFrom::get(&self.db).unwrap_or(1);
let latest_block_number =
self.serai.latest_finalized_block_number().await.map_err(|e| format!("{e:?}"))?.number();
self.serai.latest_finalized_block_number().await.map_err(|e| format!("{e:?}"))?;
for block_number in start_block_number ..= latest_block_number {
let mut txn = self.db.txn();
@@ -76,26 +80,35 @@ impl<D: Db> ContinuallyRan for CosignIntendTask<D> {
.await
.map_err(|e| format!("{e:?}"))?;
let mut builds_upon =
BuildsUpon::get(&txn).unwrap_or(IncrementalUnbalancedMerkleTree::new());
// Check we are indexing a linear chain
if (block_number > 1) &&
(<[u8; 32]>::from(block.header.parent_hash) !=
SubstrateBlockHash::get(&txn, block_number - 1)
.expect("indexing a block but haven't indexed its parent"))
if block.header.builds_upon() !=
builds_upon.clone().calculate(serai_abi::BLOCK_HEADER_BRANCH_TAG)
{
Err(format!(
"node's block #{block_number} doesn't build upon the block #{} prior indexed",
block_number - 1
))?;
}
let block_hash = block.hash();
let block_hash = block.header.hash();
SubstrateBlockHash::set(&mut txn, block_number, &block_hash);
builds_upon.append(
serai_abi::BLOCK_HEADER_BRANCH_TAG,
Blake2b256::new_with_prefix([serai_abi::BLOCK_HEADER_LEAF_TAG])
.chain_update(block_hash.0)
.finalize()
.into(),
);
BuildsUpon::set(&mut txn, &builds_upon);
let global_session_for_this_block = LatestGlobalSessionIntended::get(&txn);
// If this is notable, it creates a new global session, which we index into the database
// now
if has_events == HasEvents::Notable {
let serai = self.serai.as_of(block_hash);
let serai = self.serai.as_of(block_hash).await.map_err(|e| format!("{e:?}"))?;
let sets_and_keys = cosigning_sets(&serai).await?;
let global_session =
GlobalSession::id(sets_and_keys.iter().map(|(set, _key)| *set).collect());
@@ -109,7 +122,7 @@ impl<D: Db> ContinuallyRan for CosignIntendTask<D> {
keys.insert(set.network, SeraiAddress::from(*key));
let stake = serai
.validator_sets()
.total_allocated_stake(set.network.into())
.current_stake(set.network.into())
.await
.map_err(|e| format!("{e:?}"))?
.unwrap_or(Amount(0))

View File

@@ -11,6 +11,7 @@ use borsh::{BorshSerialize, BorshDeserialize};
use serai_abi::{
primitives::{
BlockHash,
crypto::{Public, KeyPair},
network_id::ExternalNetworkId,
validator_sets::{Session, ExternalValidatorSet},
@@ -18,7 +19,7 @@ use serai_abi::{
},
Block,
};
use serai_client::{Serai, TemporalSerai};
use serai_client_serai::{Serai, TemporalSerai};
use serai_db::*;
use serai_task::*;
@@ -86,7 +87,7 @@ create_db! {
// The following are populated by the intend task and used throughout the library
// An index of Substrate blocks
SubstrateBlockHash: (block_number: u64) -> [u8; 32],
SubstrateBlockHash: (block_number: u64) -> BlockHash,
// A mapping from a global session's ID to its relevant information.
GlobalSessions: (global_session: [u8; 32]) -> GlobalSession,
// The last block to be cosigned by a global session.
@@ -124,7 +125,7 @@ async fn keys_for_network(
network: ExternalNetworkId,
) -> Result<Option<(Session, KeyPair)>, String> {
let Some(latest_session) =
serai.validator_sets().session(network.into()).await.map_err(|e| format!("{e:?}"))?
serai.validator_sets().current_session(network.into()).await.map_err(|e| format!("{e:?}"))?
else {
// If this network hasn't had a session declared, move on
return Ok(None);
@@ -272,7 +273,10 @@ impl<D: Db> Cosigning<D> {
}
/// Fetch a cosigned Substrate block's hash by its block number.
pub fn cosigned_block(getter: &impl Get, block_number: u64) -> Result<Option<[u8; 32]>, Faulted> {
pub fn cosigned_block(
getter: &impl Get,
block_number: u64,
) -> Result<Option<BlockHash>, Faulted> {
if block_number > Self::latest_cosigned_block_number(getter)? {
return Ok(None);
}

View File

@@ -3,7 +3,7 @@
//! Types used when cosigning Serai. For more info, please see `serai-cosign`.
use borsh::{BorshSerialize, BorshDeserialize};
use serai_primitives::{crypto::Public, network_id::ExternalNetworkId};
use serai_primitives::{BlockHash, crypto::Public, network_id::ExternalNetworkId};
/// The schnorrkel context to used when signing a cosign.
pub const COSIGN_CONTEXT: &[u8] = b"/serai/coordinator/cosign";
@@ -16,7 +16,7 @@ pub struct CosignIntent {
/// The number of the block to cosign.
pub block_number: u64,
/// The hash of the block to cosign.
pub block_hash: [u8; 32],
pub block_hash: BlockHash,
/// If this cosign must be handled before further cosigns are.
pub notable: bool,
}
@@ -29,7 +29,7 @@ pub struct Cosign {
/// The number of the block to cosign.
pub block_number: u64,
/// The hash of the block to cosign.
pub block_hash: [u8; 32],
pub block_hash: BlockHash,
/// The actual cosigner.
pub cosigner: ExternalNetworkId,
}

View File

@@ -1,3 +1,5 @@
use alloc::vec::Vec;
use borsh::{BorshSerialize, BorshDeserialize};
use serai_primitives::{
@@ -96,6 +98,8 @@ pub enum Event {
SetDecided {
/// The set decided.
set: ValidatorSet,
/// The validators decided to be included in the set.
validators: Vec<(SeraiAddress, KeyShares)>,
},
/// A validator set has set their keys.
SetKeys {

View File

@@ -30,6 +30,7 @@ async-lock = "3"
[dev-dependencies]
blake2 = { version = "0.11.0-rc.3", default-features = false }
sp-core = { git = "https://github.com/serai-dex/patch-polkadot-sdk", rev = "e01101b68c5b0f588dd4cdee48f801a2c1f75b84" }
tokio = { version = "1", default-features = false, features = ["rt", "macros"] }
dockertest = "0.5"

View File

@@ -0,0 +1,76 @@
pub use serai_abi::coins::Event;
use crate::{RpcError, TemporalSerai};
/// A `TemporalSerai` scoped to the coins module.
#[derive(Clone)]
pub struct Coins<'a>(pub(super) &'a TemporalSerai<'a>);
impl<'a> Coins<'a> {
/// The events from the coins module.
pub async fn events(&self) -> Result<Vec<Event>, RpcError> {
Ok(
self
.0
.events_borrowed()
.await?
.as_ref()
.expect("`TemporalSerai::events` returned None")
.iter()
.flat_map(IntoIterator::into_iter)
.filter_map(|event| match event {
serai_abi::Event::Coins(event) => Some(event.clone()),
_ => None,
})
.collect(),
)
}
/// The `Mint` events from the coins module.
pub async fn mint_events(&self) -> Result<Vec<Event>, RpcError> {
Ok(
self
.events()
.await?
.into_iter()
.filter(|event| matches!(event, Event::Mint { .. }))
.collect(),
)
}
/// The `Transfer` events from the coins module.
pub async fn transfer_events(&self) -> Result<Vec<Event>, RpcError> {
Ok(
self
.events()
.await?
.into_iter()
.filter(|event| matches!(event, Event::Transfer { .. }))
.collect(),
)
}
/// The `Burn` events from the coins module.
pub async fn burn_events(&self) -> Result<Vec<Event>, RpcError> {
Ok(
self
.events()
.await?
.into_iter()
.filter(|event| matches!(event, Event::Burn { .. }))
.collect(),
)
}
/// The `BurnWithInstruction` events from the coins module.
pub async fn burn_with_instruction_events(&self) -> Result<Vec<Event>, RpcError> {
Ok(
self
.events()
.await?
.into_iter()
.filter(|event| matches!(event, Event::BurnWithInstruction { .. }))
.collect(),
)
}
}

View File

@@ -19,6 +19,10 @@ use abi::{
use async_lock::RwLock;
/// RPC client functionality for the coins module.
pub mod coins;
use coins::*;
/// RPC client functionality for the validator sets module.
pub mod validator_sets;
use validator_sets::*;
@@ -134,25 +138,29 @@ impl Serai {
}
async fn block_internal(
block: impl Future<Output = Result<String, RpcError>>,
) -> Result<Block, RpcError> {
block: impl Future<Output = Result<Option<String>, RpcError>>,
) -> Result<Option<Block>, RpcError> {
let bin = block.await?;
Block::deserialize(
&mut hex::decode(&bin)
.map_err(|_| RpcError::InvalidNode("node returned non-hex-encoded block".to_string()))?
.as_slice(),
)
.map_err(|_| RpcError::InvalidNode("node returned invalid block".to_string()))
bin
.map(|bin| {
Block::deserialize(
&mut hex::decode(&bin)
.map_err(|_| RpcError::InvalidNode("node returned non-hex-encoded block".to_string()))?
.as_slice(),
)
.map_err(|_| RpcError::InvalidNode("node returned invalid block".to_string()))
})
.transpose()
}
/// Fetch a block from the Serai blockchain.
pub async fn block(&self, block: BlockHash) -> Result<Block, RpcError> {
pub async fn block(&self, block: BlockHash) -> Result<Option<Block>, RpcError> {
Self::block_internal(self.call("blockchain/block", &format!(r#"{{ "block": "{block}" }}"#)))
.await
}
/// Fetch a block from the Serai blockchain by its number.
pub async fn block_by_number(&self, block: u64) -> Result<Block, RpcError> {
pub async fn block_by_number(&self, block: u64) -> Result<Option<Block>, RpcError> {
Self::block_internal(self.call("blockchain/block", &format!(r#"{{ "block": {block} }}"#))).await
}
@@ -241,6 +249,11 @@ impl<'a> TemporalSerai<'a> {
Ok(self.events_borrowed().await?.clone().expect("`TemporalSerai::events` returned None"))
}
/// Scope to the coins module.
pub fn coins(&self) -> Coins<'_> {
Coins(self)
}
/// Scope to the validator sets module.
pub fn validator_sets(&self) -> ValidatorSets<'_> {
ValidatorSets(self)

View File

@@ -49,8 +49,8 @@ async fn blockchain() {
let test_finalized_block = |number| {
let serai = &serai;
async move {
let block = serai.block_by_number(number).await.unwrap();
assert_eq!(serai.block(block.header.hash()).await.unwrap(), block);
let block = serai.block_by_number(number).await.unwrap().unwrap();
assert_eq!(serai.block(block.header.hash()).await.unwrap().unwrap(), block);
assert!(serai.finalized(block.header.hash()).await.unwrap());
}
};
@@ -70,7 +70,7 @@ async fn blockchain() {
continue;
};
// Check if it's considered finalized
let considered_finalized = serai.finalized(block.header.hash()).await.unwrap();
let considered_finalized = serai.finalized(block.unwrap().header.hash()).await.unwrap();
// Ensure the finalized block is the same, meaning this block didn't become finalized as
// we made these RPC requests
if latest_finalized != serai.latest_finalized_block_number().await.unwrap() {
@@ -108,7 +108,7 @@ async fn blockchain() {
let mut observed_consensus_commitments = HashSet::new();
let mut tagged_block_hashes = vec![];
for i in 0 ..= last_block_number {
let block = serai.block_by_number(i).await.unwrap();
let block = serai.block_by_number(i).await.unwrap().unwrap();
assert_eq!(block.header.number(), i);

View File

@@ -1,8 +1,9 @@
use serai_abi::{
primitives::{
address::SeraiAddress,
network_id::{ExternalNetworkId, NetworkId},
balance::Amount,
validator_sets::{Session, ExternalValidatorSet, ValidatorSet},
validator_sets::{Session, ExternalValidatorSet, ValidatorSet, KeyShares},
},
validator_sets::Event,
};
@@ -43,11 +44,16 @@ async fn validator_sets() {
panic!("finalized block remained the genesis block for over five minutes");
};
// The genesis block should have the expected events
{
use sp_core::{Pair as _, sr25519::Pair};
let genesis_validators = vec![(
SeraiAddress::from(Pair::from_string("//Alice", None).unwrap().public()),
KeyShares(1),
)];
// The genesis block should have the expected events
{
let mut events = serai
.as_of(serai.block_by_number(0).await.unwrap().header.hash())
.as_of(serai.block_by_number(0).await.unwrap().unwrap().header.hash())
.await
.unwrap()
.validator_sets()
@@ -58,27 +64,32 @@ async fn validator_sets() {
let mut expected = vec![
Event::SetDecided {
set: ValidatorSet { network: NetworkId::Serai, session: Session(0) },
validators: genesis_validators.clone(),
},
Event::SetDecided {
set: ValidatorSet { network: NetworkId::Serai, session: Session(1) },
validators: genesis_validators.clone(),
},
Event::SetDecided {
set: ValidatorSet {
network: NetworkId::External(ExternalNetworkId::Bitcoin),
session: Session(0),
},
validators: genesis_validators.clone(),
},
Event::SetDecided {
set: ValidatorSet {
network: NetworkId::External(ExternalNetworkId::Ethereum),
session: Session(0),
},
validators: genesis_validators.clone(),
},
Event::SetDecided {
set: ValidatorSet {
network: NetworkId::External(ExternalNetworkId::Monero),
session: Session(0),
},
validators: genesis_validators.clone(),
},
];
expected.sort_by_key(|event| borsh::to_vec(event).unwrap());
@@ -87,7 +98,7 @@ async fn validator_sets() {
assert_eq!(
serai
.as_of(serai.block_by_number(0).await.unwrap().header.hash())
.as_of(serai.block_by_number(0).await.unwrap().unwrap().header.hash())
.await
.unwrap()
.validator_sets()
@@ -104,7 +115,7 @@ async fn validator_sets() {
{
assert_eq!(
serai
.as_of(serai.block_by_number(1).await.unwrap().header.hash())
.as_of(serai.block_by_number(1).await.unwrap().unwrap().header.hash())
.await
.unwrap()
.validator_sets()
@@ -115,7 +126,7 @@ async fn validator_sets() {
);
assert_eq!(
serai
.as_of(serai.block_by_number(1).await.unwrap().header.hash())
.as_of(serai.block_by_number(1).await.unwrap().unwrap().header.hash())
.await
.unwrap()
.validator_sets()
@@ -127,8 +138,10 @@ async fn validator_sets() {
}
{
let serai =
serai.as_of(serai.block_by_number(0).await.unwrap().header.hash()).await.unwrap();
let serai = serai
.as_of(serai.block_by_number(0).await.unwrap().unwrap().header.hash())
.await
.unwrap();
let serai = serai.validator_sets();
for network in NetworkId::all() {
match network {

View File

@@ -37,10 +37,12 @@ pub(crate) fn module<
module.register_method(
"blockchain/is_finalized",
|params, client, _ext| -> Result<_, Error> {
let block_hash = block_hash(&**client, &params)?;
let Some(block_hash) = block_hash(&**client, &params)? else {
return Ok(false);
};
let finalized = client.info().finalized_number;
let Ok(Some(number)) = client.number(block_hash) else {
Err(Error::Missing("failed to fetch block's number"))?
return Ok(false);
};
let Ok(status) = client.block_status(block_hash) else {
Err(Error::Internal("failed to fetch block's status"))?
@@ -53,18 +55,22 @@ pub(crate) fn module<
)?;
module.register_method("blockchain/block", |params, client, _ext| -> Result<_, Error> {
let block_hash = block_hash(&**client, &params)?;
let Some(block_hash) = block_hash(&**client, &params)? else {
return Ok(None);
};
let Ok(Some(block)) = client.block(block_hash) else {
Err(Error::Missing("couldn't find requested block"))?
return Ok(None);
};
Ok(hex::encode(borsh::to_vec(&serai_abi::Block::from(block.block)).unwrap()))
Ok(Some(hex::encode(borsh::to_vec(&serai_abi::Block::from(block.block)).unwrap())))
})?;
module.register_method("blockchain/events", |params, client, _ext| -> Result<_, Error> {
let block_hash = block_hash(&**client, &params)?;
let Some(block_hash) = block_hash(&**client, &params)? else {
Err(Error::InvalidStateReference)?
};
let Ok(events) = client.runtime_api().events(block_hash) else {
Err(Error::Missing("couldn't fetch the events for the requested block"))?
Err(Error::InvalidStateReference)?
};
Ok(
events

View File

@@ -6,7 +6,7 @@ use serai_abi::{primitives::prelude::*, SubstrateBlock as Block};
pub(super) enum Error {
Internal(&'static str),
InvalidRequest(&'static str),
Missing(&'static str),
InvalidStateReference,
}
impl From<Error> for jsonrpsee::types::error::ErrorObjectOwned {
@@ -18,9 +18,11 @@ impl From<Error> for jsonrpsee::types::error::ErrorObjectOwned {
Error::InvalidRequest(str) => {
jsonrpsee::types::error::ErrorObjectOwned::owned(-2, str, Option::<()>::None)
}
Error::Missing(str) => {
jsonrpsee::types::error::ErrorObjectOwned::owned(-3, str, Option::<()>::None)
}
Error::InvalidStateReference => jsonrpsee::types::error::ErrorObjectOwned::owned(
-4,
"the block used as the reference was not locally held",
Option::<()>::None,
),
}
}
}
@@ -30,7 +32,7 @@ pub(super) fn block_hash<
>(
client: &C,
params: &jsonrpsee::types::params::Params,
) -> Result<<Block as sp_runtime::traits::Block>::Hash, Error> {
) -> Result<Option<<Block as sp_runtime::traits::Block>::Hash>, Error> {
#[derive(sp_core::serde::Deserialize)]
#[serde(crate = "sp_core::serde")]
struct BlockByHash {
@@ -50,13 +52,13 @@ pub(super) fn block_hash<
}) else {
return Err(Error::InvalidRequest("requested block hash wasn't a valid hash"));
};
block_hash
Some(block_hash)
} else {
let Ok(block_number) = params.parse::<BlockByNumber>() else {
return Err(Error::InvalidRequest("requested block wasn't a valid hash nor number"));
};
let Ok(Some(block_hash)) = client.block_hash(block_number.block) else {
return Err(Error::Missing("no block hash for that block number"));
let Ok(block_hash) = client.block_hash(block_number.block) else {
return Err(Error::Internal("couldn't fetch block hash for block number"));
};
block_hash
})

View File

@@ -72,7 +72,9 @@ pub(crate) fn module<
module.register_method(
"validator-sets/current_session",
|params, client, _ext| -> Result<_, Error> {
let block_hash = block_hash(&**client, &params)?;
let Some(block_hash) = block_hash(&**client, &params)? else {
Err(Error::InvalidStateReference)?
};
let network = network(&params)?;
let Ok(session) = client.runtime_api().current_session(block_hash, network) else {
Err(Error::Internal("couldn't fetch the session for the requested network"))?
@@ -84,7 +86,9 @@ pub(crate) fn module<
module.register_method(
"validator-sets/current_stake",
|params, client, _ext| -> Result<_, Error> {
let block_hash = block_hash(&**client, &params)?;
let Some(block_hash) = block_hash(&**client, &params)? else {
Err(Error::InvalidStateReference)?
};
let network = network(&params)?;
let Ok(stake) = client.runtime_api().current_stake(block_hash, network) else {
Err(Error::Internal("couldn't fetch the total allocated stake for the requested network"))?
@@ -94,7 +98,9 @@ pub(crate) fn module<
);
module.register_method("validator-sets/keys", |params, client, _ext| -> Result<_, Error> {
let block_hash = block_hash(&**client, &params)?;
let Some(block_hash) = block_hash(&**client, &params)? else {
Err(Error::InvalidStateReference)?
};
let set = set(&params)?;
let Ok(set) = ExternalValidatorSet::try_from(set) else {
Err(Error::InvalidRequest("requested keys for a non-external validator set"))?

View File

@@ -65,6 +65,17 @@ impl From<SeraiAddress> for Public {
}
}
impl From<crate::crypto::Public> for SeraiAddress {
fn from(key: crate::crypto::Public) -> Self {
Public::from(key).into()
}
}
impl From<SeraiAddress> for crate::crypto::Public {
fn from(address: SeraiAddress) -> Self {
Public::from(address).into()
}
}
// We use Bech32m to encode addresses
impl core::fmt::Display for SeraiAddress {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {

View File

@@ -73,7 +73,7 @@ impl UnbalancedMerkleTree {
}
/// An unbalanced Merkle tree which is incrementally created.
#[derive(Clone, PartialEq, Eq, Debug)]
#[derive(Clone, PartialEq, Eq, Debug, BorshSerialize, BorshDeserialize)]
#[cfg_attr(
feature = "non_canonical_scale_derivations",
derive(scale::Encode, scale::Decode, scale::DecodeWithMemTracking)

View File

@@ -326,14 +326,20 @@ impl<Storage: SessionsStorage> Sessions for Storage {
latest_decided_set,
KeySharesStruct::try_from(total_key_shares).expect("amortization failure"),
);
for (key, key_shares) in selected_validators {
for (key, key_shares) in &selected_validators {
Storage::SelectedValidators::insert(
selected_validators_key(latest_decided_set, key),
selected_validators_key(latest_decided_set, *key),
key_shares,
);
}
Core::<Storage::Config>::emit_event(Event::SetDecided { set: latest_decided_set });
Core::<Storage::Config>::emit_event(Event::SetDecided {
set: latest_decided_set,
validators: selected_validators
.into_iter()
.map(|(key, key_shares)| (key.into(), key_shares))
.collect(),
});
true
}