solana-wasi 0.1.0

//! A small, typed JSON-RPC client.
//!
//! Only the methods a tool plugin actually needs are modelled. Each one returns
//! a Rust type rather than a `serde_json::Value`, because the whole point of
//! this crate is that the plugin above it never hand-parses an RPC response and
//! never accidentally forwards 40KB of it into a model's context window.

use std::cell::Cell;

use base64::Engine;
use serde::Deserialize;
use serde_json::{json, Value};

use crate::error::{Error, Result};
use crate::pubkey::Pubkey;
use crate::transport::Transport;

/// Commitment level sent with every request that accepts one.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Commitment {
    /// Seen by this node, may still be dropped.
    Processed,
    /// Voted on by a supermajority. The default.
    #[default]
    Confirmed,
    /// Rooted; will not be rolled back.
    Finalized,
}

impl Commitment {
    /// The wire string.
    pub const fn as_str(self) -> &'static str {
        match self {
            Commitment::Processed => "processed",
            Commitment::Confirmed => "confirmed",
            Commitment::Finalized => "finalized",
        }
    }
}

/// A fetched account, with `data` already base64-decoded.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Account {
    /// Balance in lamports.
    pub lamports: u64,
    /// The program that owns, and may write to, this account.
    pub owner: Pubkey,
    /// Raw account data, already base64-decoded.
    pub data: Vec<u8>,
    /// True for a program account.
    pub executable: bool,
    /// Legacy rent field; kept for completeness.
    pub rent_epoch: u64,
}

/// A token amount as the RPC reports it.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
pub struct UiTokenAmount {
    /// Raw base units, as a string because it does not fit a JS number.
    pub amount: String,
    /// Decimal places the mint declares.
    pub decimals: u8,
    /// The node's own rendering of `amount`, when it supplied one.
    #[serde(default)]
    pub ui_amount_string: String,
}

/// One row of `getTokenLargestAccounts`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TokenAccountBalance {
    /// The token account, not its owner.
    pub address: Pubkey,
    /// Balance in base units.
    pub amount: u128,
    /// Decimal places the mint declares.
    pub decimals: u8,
}

/// The pair `getLatestBlockhash` returns.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LatestBlockhash {
    /// Base58 blockhash to put in a message.
    pub blockhash: String,
    /// Last block height at which a transaction using it is still accepted.
    pub last_valid_block_height: u64,
}

/// The interesting part of a `simulateTransaction` response.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SimulationOutcome {
    /// `None` means the transaction simulated successfully.
    pub err: Option<String>,
    /// Program log lines, in order.
    pub logs: Vec<String>,
    /// Compute units the simulation used.
    pub units_consumed: Option<u64>,
}

/// A JSON-RPC client bound to one endpoint and one [`Transport`].
pub struct RpcClient<T: Transport> {
    url: String,
    transport: T,
    commitment: Commitment,
    next_id: Cell<u64>,
}

impl<T: Transport> RpcClient<T> {
    /// Bind to an endpoint.
    pub fn new(url: impl Into<String>, transport: T) -> Self {
        Self {
            url: url.into(),
            transport,
            commitment: Commitment::default(),
            next_id: Cell::new(1),
        }
    }

    /// Set the commitment used by every subsequent call.
    pub fn with_commitment(mut self, commitment: Commitment) -> Self {
        self.commitment = commitment;
        self
    }

    /// The endpoint with any credential material removed.
    ///
    /// Operators put their API key in the RPC URL (`…/?api-key=…`, or as a path
    /// segment). Use this — never `self.url` — in anything that reaches a log
    /// line, an error message, or a model's context.
    pub fn safe_endpoint(&self) -> String {
        redact_endpoint(&self.url)
    }

    fn call(&self, method: &str, params: Value) -> Result<Value> {
        let id = self.next_id.get();
        self.next_id.set(id.wrapping_add(1));

        let body = json!({
            "jsonrpc": "2.0",
            "id": id,
            "method": method,
            "params": params,
        })
        .to_string();

        let raw = self.transport.post_json(&self.url, &body)?;
        let parsed: Value = serde_json::from_str(&raw)
            .map_err(|e| Error::UnexpectedResponse(format!("{method}: not JSON: {e}")))?;

        if let Some(err) = parsed.get("error") {
            let code = err.get("code").and_then(Value::as_i64).unwrap_or(0);
            let message = err
                .get("message")
                .and_then(Value::as_str)
                .unwrap_or("unknown")
                .chars()
                .take(200)
                .collect();
            return Err(Error::Rpc { code, message });
        }

        parsed
            .get("result")
            .cloned()
            .ok_or_else(|| Error::UnexpectedResponse(format!("{method}: no result member")))
    }

    fn commitment_cfg(&self) -> Value {
        json!({ "commitment": self.commitment.as_str() })
    }

    /// `getAccountInfo`. `Ok(None)` when the account does not exist.
    pub fn get_account(&self, address: &Pubkey) -> Result<Option<Account>> {
        let result = self.call(
            "getAccountInfo",
            json!([
                address.to_base58(),
                { "encoding": "base64", "commitment": self.commitment.as_str() }
            ]),
        )?;
        parse_account(result.get("value").unwrap_or(&Value::Null))
    }

    /// `getAccountInfo`, erroring when the account is missing.
    pub fn require_account(&self, address: &Pubkey) -> Result<Account> {
        self.get_account(address)?
            .ok_or_else(|| Error::AccountNotFound(address.to_base58()))
    }

    /// `getMultipleAccounts`. One round trip for up to 100 addresses; prefer
    /// this over a loop of `get_account`, both for latency and because most
    /// providers rate-limit on requests, not on bytes.
    pub fn get_multiple_accounts(&self, addresses: &[Pubkey]) -> Result<Vec<Option<Account>>> {
        if addresses.is_empty() {
            return Ok(Vec::new());
        }
        if addresses.len() > 100 {
            return Err(Error::InvalidArgument(
                "getMultipleAccounts accepts at most 100 addresses".into(),
            ));
        }
        let keys: Vec<String> = addresses.iter().map(Pubkey::to_base58).collect();
        let result = self.call(
            "getMultipleAccounts",
            json!([
                keys,
                { "encoding": "base64", "commitment": self.commitment.as_str() }
            ]),
        )?;
        let values = result
            .get("value")
            .and_then(Value::as_array)
            .ok_or_else(|| Error::UnexpectedResponse("getMultipleAccounts: no value".into()))?;
        values.iter().map(parse_account).collect()
    }

    /// `getBalance`, in lamports.
    pub fn get_balance(&self, address: &Pubkey) -> Result<u64> {
        let result = self.call(
            "getBalance",
            json!([address.to_base58(), self.commitment_cfg()]),
        )?;
        result
            .get("value")
            .and_then(Value::as_u64)
            .ok_or_else(|| Error::UnexpectedResponse("getBalance: no value".into()))
    }

    /// `getLatestBlockhash`.
    pub fn get_latest_blockhash(&self) -> Result<LatestBlockhash> {
        let result = self.call("getLatestBlockhash", json!([self.commitment_cfg()]))?;
        let value = result
            .get("value")
            .ok_or_else(|| Error::UnexpectedResponse("getLatestBlockhash: no value".into()))?;
        Ok(LatestBlockhash {
            blockhash: value
                .get("blockhash")
                .and_then(Value::as_str)
                .ok_or_else(|| Error::UnexpectedResponse("getLatestBlockhash: no blockhash".into()))?
                .to_string(),
            last_valid_block_height: value
                .get("lastValidBlockHeight")
                .and_then(Value::as_u64)
                .unwrap_or_default(),
        })
    }

    /// `getSlot`.
    pub fn get_slot(&self) -> Result<u64> {
        self.call("getSlot", json!([self.commitment_cfg()]))?
            .as_u64()
            .ok_or_else(|| Error::UnexpectedResponse("getSlot: not a number".into()))
    }

    /// `getTokenSupply`.
    pub fn get_token_supply(&self, mint: &Pubkey) -> Result<UiTokenAmount> {
        let result = self.call(
            "getTokenSupply",
            json!([mint.to_base58(), self.commitment_cfg()]),
        )?;
        let value = result
            .get("value")
            .ok_or_else(|| Error::UnexpectedResponse("getTokenSupply: no value".into()))?;
        Ok(UiTokenAmount {
            amount: value
                .get("amount")
                .and_then(Value::as_str)
                .unwrap_or("0")
                .to_string(),
            decimals: value.get("decimals").and_then(Value::as_u64).unwrap_or(0) as u8,
            ui_amount_string: value
                .get("uiAmountString")
                .and_then(Value::as_str)
                .unwrap_or_default()
                .to_string(),
        })
    }

    /// `getTokenLargestAccounts` — the top 20 holders by balance.
    pub fn get_token_largest_accounts(&self, mint: &Pubkey) -> Result<Vec<TokenAccountBalance>> {
        let result = self.call(
            "getTokenLargestAccounts",
            json!([mint.to_base58(), self.commitment_cfg()]),
        )?;
        let rows = result
            .get("value")
            .and_then(Value::as_array)
            .ok_or_else(|| Error::UnexpectedResponse("getTokenLargestAccounts: no value".into()))?;

        let mut out = Vec::with_capacity(rows.len());
        for row in rows {
            let address = row
                .get("address")
                .and_then(Value::as_str)
                .ok_or_else(|| Error::UnexpectedResponse("largest accounts: no address".into()))?;
            let amount = row
                .get("amount")
                .and_then(Value::as_str)
                .unwrap_or("0")
                .parse::<u128>()
                .unwrap_or(0);
            out.push(TokenAccountBalance {
                address: Pubkey::from_base58(address)?,
                amount,
                decimals: row.get("decimals").and_then(Value::as_u64).unwrap_or(0) as u8,
            });
        }
        Ok(out)
    }

    /// `getMinimumBalanceForRentExemption`.
    pub fn get_minimum_balance_for_rent_exemption(&self, data_len: usize) -> Result<u64> {
        self.call("getMinimumBalanceForRentExemption", json!([data_len]))?
            .as_u64()
            .ok_or_else(|| Error::UnexpectedResponse("rent exemption: not a number".into()))
    }

    /// `simulateTransaction` with `sigVerify: false`.
    ///
    /// The point of simulating an *unsigned* transaction is that a T1 builder
    /// can prove the thing it is about to hand a human will actually land,
    /// before the human is asked to approve it.
    pub fn simulate_unsigned(&self, tx_base64: &str) -> Result<SimulationOutcome> {
        let result = self.call(
            "simulateTransaction",
            json!([
                tx_base64,
                {
                    "encoding": "base64",
                    "sigVerify": false,
                    "replaceRecentBlockhash": false,
                    "commitment": self.commitment.as_str(),
                }
            ]),
        )?;
        let value = result
            .get("value")
            .ok_or_else(|| Error::UnexpectedResponse("simulateTransaction: no value".into()))?;
        Ok(SimulationOutcome {
            err: match value.get("err") {
                None | Some(Value::Null) => None,
                Some(e) => Some(e.to_string().chars().take(300).collect()),
            },
            logs: value
                .get("logs")
                .and_then(Value::as_array)
                .map(|l| {
                    l.iter()
                        .filter_map(Value::as_str)
                        .map(str::to_string)
                        .collect()
                })
                .unwrap_or_default(),
            units_consumed: value.get("unitsConsumed").and_then(Value::as_u64),
        })
    }

    /// Escape hatch for a method this crate does not model.
    pub fn raw_call(&self, method: &str, params: Value) -> Result<Value> {
        self.call(method, params)
    }
}

fn parse_account(value: &Value) -> Result<Option<Account>> {
    if value.is_null() {
        return Ok(None);
    }
    let owner = value
        .get("owner")
        .and_then(Value::as_str)
        .ok_or_else(|| Error::UnexpectedResponse("account: no owner".into()))?;

    let data = match value.get("data") {
        // ["<base64>", "base64"]
        Some(Value::Array(parts)) => {
            let encoded = parts
                .first()
                .and_then(Value::as_str)
                .ok_or_else(|| Error::UnexpectedResponse("account: empty data array".into()))?;
            let encoding = parts.get(1).and_then(Value::as_str).unwrap_or("base64");
            if encoding != "base64" {
                return Err(Error::UnexpectedResponse(format!(
                    "account: unsupported data encoding `{encoding}`"
                )));
            }
            base64::engine::general_purpose::STANDARD
                .decode(encoded)
                .map_err(|e| Error::UnexpectedResponse(format!("account: bad base64: {e}")))?
        }
        // jsonParsed responses; this crate never asks for them.
        Some(Value::Object(_)) => {
            return Err(Error::UnexpectedResponse(
                "account: jsonParsed encoding is not supported, request base64".into(),
            ))
        }
        _ => Vec::new(),
    };

    Ok(Some(Account {
        lamports: value.get("lamports").and_then(Value::as_u64).unwrap_or(0),
        owner: Pubkey::from_base58(owner)?,
        data,
        executable: value
            .get("executable")
            .and_then(Value::as_bool)
            .unwrap_or(false),
        rent_epoch: value.get("rentEpoch").and_then(Value::as_u64).unwrap_or(0),
    }))
}

/// Strip credential material from an RPC endpoint so it is safe to print.
///
/// Handles the two shapes every provider uses: a query parameter
/// (`?api-key=…`) and a trailing path segment (`/v2/<uuid>`). Anything that is
/// not a bare `scheme://host` collapses to `scheme://host/…`.
pub fn redact_endpoint(url: &str) -> String {
    let (scheme, rest) = match url.split_once("://") {
        Some((s, r)) => (s, r),
        None => return "…".to_string(),
    };
    let host_end = rest.find(['/', '?']).unwrap_or(rest.len());
    let host = &rest[..host_end];
    // Credentials can also be smuggled in userinfo (`user:pass@host`).
    let host = host.rsplit('@').next().unwrap_or(host);
    if host_end == rest.len() {
        format!("{scheme}://{host}")
    } else {
        format!("{scheme}://{host}/…")
    }
}