diff --git a/python/kaspa/__init__.pyi b/python/kaspa/__init__.pyi index 480e65ad..da8087e4 100644 --- a/python/kaspa/__init__.pyi +++ b/python/kaspa/__init__.pyi @@ -8,6 +8,13 @@ from . import exceptions @typing.final class AccountDescriptor: + r""" + A read-only snapshot describing a wallet account. + + Exposes the account's kind, id, name, balance, addresses, and derivation + metadata. Returned by `Wallet` account enumeration, creation, and + activation methods. + """ @property def kind(self) -> AccountKind: r""" @@ -368,15 +375,49 @@ class CovenantBinding: Binds a transaction output to the covenant and input authorizing its creation. """ @property - def authorizing_input(self) -> builtins.int: ... + def authorizing_input(self) -> builtins.int: + r""" + The index of the transaction input authorizing the covenant. + """ @authorizing_input.setter - def authorizing_input(self, value: builtins.int) -> None: ... + def authorizing_input(self, value: builtins.int) -> None: + r""" + Set the authorizing input index. + + Args: + value: The index of the transaction input authorizing the covenant. + """ @property - def covenant_id(self) -> Hash: ... + def covenant_id(self) -> Hash: + r""" + The covenant id the output is bound to. + """ @covenant_id.setter - def covenant_id(self, value: Hash) -> None: ... - def __new__(cls, authorizing_input: builtins.int, covenant_id: Hash) -> CovenantBinding: ... - def __repr__(self) -> builtins.str: ... + def covenant_id(self, value: Hash) -> None: + r""" + Set the covenant id. + + Args: + value: The covenant id the output is bound to. + """ + def __new__(cls, authorizing_input: builtins.int, covenant_id: Hash) -> CovenantBinding: + r""" + Create a new CovenantBinding. + + Args: + authorizing_input: The index of the transaction input authorizing the covenant. + covenant_id: The covenant id the output is bound to. + + Returns: + CovenantBinding: A new CovenantBinding instance. + """ + def __repr__(self) -> builtins.str: + r""" + The detailed string representation. + + Returns: + str: The CovenantBinding as a repr string. + """ @typing.final class DerivationPath: @@ -627,11 +668,37 @@ class GeneratorSummary: @typing.final class GenesisCovenantGroup: + r""" + A genesis covenant group for bulk covenant binding population. + + All listed outputs are bound to the same covenant id, derived from the + authorizing input outpoint and the exact ordered output list. Used with + `Transaction.populate_genesis_covenants`. + """ @property - def authorizing_input(self) -> builtins.int: ... + def authorizing_input(self) -> builtins.int: + r""" + The index of the transaction input authorizing the covenant. + """ @authorizing_input.setter - def authorizing_input(self, value: builtins.int) -> None: ... - def __new__(cls, authorizing_input: builtins.int, outputs: typing.Sequence[builtins.int]) -> GenesisCovenantGroup: ... + def authorizing_input(self, value: builtins.int) -> None: + r""" + Set the authorizing input index. + + Args: + value: The index of the transaction input authorizing the covenant. + """ + def __new__(cls, authorizing_input: builtins.int, outputs: typing.Sequence[builtins.int]) -> GenesisCovenantGroup: + r""" + Create a new GenesisCovenantGroup. + + Args: + authorizing_input: The index of the transaction input authorizing the covenant. + outputs: The indices of the transaction outputs to bind to the covenant. + + Returns: + GenesisCovenantGroup: A new GenesisCovenantGroup instance. + """ @typing.final class Hash: @@ -1017,7 +1084,18 @@ class PaymentOutput: amount: The amount, in sompi, to send on this output. """ @staticmethod - def with_covenant(address: Address, amount: builtins.int, covenant: CovenantBinding) -> PaymentOutput: ... + def with_covenant(address: Address, amount: builtins.int, covenant: CovenantBinding) -> PaymentOutput: + r""" + Create a new Payment Output bound to a covenant. + + Args: + address: The address to send this output to. + amount: The amount, in sompi, to send on this output. + covenant: The covenant binding to attach to this output. + + Returns: + PaymentOutput: A new PaymentOutput instance. + """ def __eq__(self, other: PaymentOutput) -> builtins.bool: r""" Equality comparison. @@ -1348,6 +1426,13 @@ class PrvKeyDataId: @typing.final class PrvKeyDataInfo: + r""" + Metadata describing a private key data entry stored in a wallet file. + + Exposes the entry's id, optional user-assigned name, and whether the + underlying key material requires a payment secret (BIP39 passphrase). + Returned by `Wallet.prv_key_data_enumerate`. + """ @property def id(self) -> PrvKeyDataId: r""" @@ -2472,7 +2557,24 @@ class Transaction: Returns: list[Address]: List of unique addresses referenced by inputs. """ - def populate_genesis_covenants(self, groups: typing.Sequence[GenesisCovenantGroup]) -> None: ... + def populate_genesis_covenants(self, groups: typing.Sequence[GenesisCovenantGroup]) -> None: + r""" + Populate genesis covenant bindings for multiple output groups. + + For each group, computes the covenant id from the authorizing input + outpoint and the group's output list, then sets that binding on all + listed outputs. All groups are validated before the transaction is + mutated. + + Args: + groups: The genesis covenant groups to populate. + + Raises: + Exception: If a group references a non-existent input or output, + output indices are not strictly increasing, outputs overlap + across groups, or a targeted output already has a covenant + binding. + """ def to_dict(self) -> dict: r""" Get a dictionary representation of the Transaction. @@ -3231,6 +3333,15 @@ class UtxoProcessor: @typing.final class Wallet: + r""" + A managed Kaspa wallet with persistent encrypted on-disk storage. + + The SDK's high-level wallet. Provides encrypted storage for keys and + account metadata, multi-account management (BIP32 and keypair accounts), + address derivation and discovery, built-in send, transfer, and sweep + flows, transaction history tracking, and an event bus for chain + notifications (balance, maturity, reorg). + """ @property def rpc(self) -> RpcClient: r""" @@ -3834,6 +3945,12 @@ class Wallet: @typing.final class WalletDescriptor: + r""" + Describes a wallet file in the wallet store. + + Pairs the on-disk wallet filename with its optional user-assigned title. + Returned by `Wallet.wallet_enumerate`. + """ @property def title(self) -> typing.Optional[builtins.str]: r""" diff --git a/src/consensus/client/covenant.rs b/src/consensus/client/covenant.rs index 8cf41f0e..b70d90d2 100644 --- a/src/consensus/client/covenant.rs +++ b/src/consensus/client/covenant.rs @@ -16,32 +16,54 @@ pub struct PyCovenantBinding(CovenantBinding); #[gen_stub_pymethods] #[pymethods] impl PyCovenantBinding { + /// Create a new CovenantBinding. + /// + /// Args: + /// authorizing_input: The index of the transaction input authorizing the covenant. + /// covenant_id: The covenant id the output is bound to. + /// + /// Returns: + /// CovenantBinding: A new CovenantBinding instance. #[new] pub fn new(authorizing_input: u16, covenant_id: PyHash) -> Self { let inner = CovenantBinding::new(authorizing_input, covenant_id.into()); Self(inner) } + /// The index of the transaction input authorizing the covenant. #[getter] pub fn get_authorizing_input(&self) -> u16 { self.0.get_authorizing_input() } + /// Set the authorizing input index. + /// + /// Args: + /// value: The index of the transaction input authorizing the covenant. #[setter] pub fn set_authorizing_input(&mut self, value: u16) { self.0.set_authorizing_input(value); } + /// The covenant id the output is bound to. #[getter] pub fn get_covenant_id(&self) -> PyHash { self.0.get_covenant_id().into() } + /// Set the covenant id. + /// + /// Args: + /// value: The covenant id the output is bound to. #[setter] pub fn set_covenant_id(&mut self, value: PyHash) { self.0.set_covenant_id(value.into()); } + /// The detailed string representation. + /// + /// Returns: + /// str: The CovenantBinding as a repr string. pub fn __repr__(&self) -> String { format!( "CovenantBinding(authorizing_input={}, covenant_id={})", @@ -86,6 +108,11 @@ impl<'a, 'py> FromPyObject<'a, 'py> for PyCovenantBinding { } } +/// A genesis covenant group for bulk covenant binding population. +/// +/// All listed outputs are bound to the same covenant id, derived from the +/// authorizing input outpoint and the exact ordered output list. Used with +/// `Transaction.populate_genesis_covenants`. #[gen_stub_pyclass] #[pyclass(name = "GenesisCovenantGroup")] #[derive(Clone)] @@ -94,6 +121,14 @@ pub struct PyGenesisCovenantGroup(GenesisCovenantGroup); #[gen_stub_pymethods] #[pymethods] impl PyGenesisCovenantGroup { + /// Create a new GenesisCovenantGroup. + /// + /// Args: + /// authorizing_input: The index of the transaction input authorizing the covenant. + /// outputs: The indices of the transaction outputs to bind to the covenant. + /// + /// Returns: + /// GenesisCovenantGroup: A new GenesisCovenantGroup instance. #[new] pub fn constructor(authorizing_input: u16, outputs: Vec) -> Self { // TODO this tmp construction process is temporary @@ -103,11 +138,16 @@ impl PyGenesisCovenantGroup { Self(inner) } + /// The index of the transaction input authorizing the covenant. #[getter] pub fn get_authorizing_input(&self) -> u16 { self.0.authorizing_input() } + /// Set the authorizing input index. + /// + /// Args: + /// value: The index of the transaction input authorizing the covenant. #[setter] pub fn set_authorizing_input(&mut self, value: u16) { self.0.set_authorizing_input(value); diff --git a/src/consensus/client/transaction.rs b/src/consensus/client/transaction.rs index e117630e..7e7e0e81 100644 --- a/src/consensus/client/transaction.rs +++ b/src/consensus/client/transaction.rs @@ -309,6 +309,21 @@ impl PyTransaction { self.0.inner().storage_mass = value; } + /// Populate genesis covenant bindings for multiple output groups. + /// + /// For each group, computes the covenant id from the authorizing input + /// outpoint and the group's output list, then sets that binding on all + /// listed outputs. All groups are validated before the transaction is + /// mutated. + /// + /// Args: + /// groups: The genesis covenant groups to populate. + /// + /// Raises: + /// Exception: If a group references a non-existent input or output, + /// output indices are not strictly increasing, outputs overlap + /// across groups, or a targeted output already has a covenant + /// binding. pub fn populate_genesis_covenants(&self, groups: Vec) -> PyResult<()> { let groups = groups .into_iter() diff --git a/src/wallet/core/account/descriptor.rs b/src/wallet/core/account/descriptor.rs index 2896733b..23c0d486 100644 --- a/src/wallet/core/account/descriptor.rs +++ b/src/wallet/core/account/descriptor.rs @@ -13,6 +13,11 @@ use kaspa_wallet_core::{ use pyo3::prelude::*; use pyo3_stub_gen::derive::{gen_stub_pyclass, gen_stub_pymethods}; +/// A read-only snapshot describing a wallet account. +/// +/// Exposes the account's kind, id, name, balance, addresses, and derivation +/// metadata. Returned by `Wallet` account enumeration, creation, and +/// activation methods. #[gen_stub_pyclass] #[pyclass(name = "AccountDescriptor")] #[derive(Clone)] diff --git a/src/wallet/core/storage/interface.rs b/src/wallet/core/storage/interface.rs index cc204c49..c7c4f040 100644 --- a/src/wallet/core/storage/interface.rs +++ b/src/wallet/core/storage/interface.rs @@ -2,6 +2,10 @@ use kaspa_wallet_core::storage::WalletDescriptor; use pyo3::prelude::*; use pyo3_stub_gen::derive::*; +/// Describes a wallet file in the wallet store. +/// +/// Pairs the on-disk wallet filename with its optional user-assigned title. +/// Returned by `Wallet.wallet_enumerate`. #[gen_stub_pyclass] #[pyclass(name = "WalletDescriptor")] pub struct PyWalletDescriptor(WalletDescriptor); diff --git a/src/wallet/core/storage/keydata.rs b/src/wallet/core/storage/keydata.rs index 52e85dae..81aa35ff 100644 --- a/src/wallet/core/storage/keydata.rs +++ b/src/wallet/core/storage/keydata.rs @@ -141,6 +141,11 @@ impl<'py> FromPyObject<'_, 'py> for PyPrvKeyDataId { } } +/// Metadata describing a private key data entry stored in a wallet file. +/// +/// Exposes the entry's id, optional user-assigned name, and whether the +/// underlying key material requires a payment secret (BIP39 passphrase). +/// Returned by `Wallet.prv_key_data_enumerate`. #[gen_stub_pyclass] #[pyclass(name = "PrvKeyDataInfo")] pub struct PyPrvKeyDataInfo(PrvKeyDataInfo); diff --git a/src/wallet/core/tx/payment.rs b/src/wallet/core/tx/payment.rs index 4f2dbc36..7843c567 100644 --- a/src/wallet/core/tx/payment.rs +++ b/src/wallet/core/tx/payment.rs @@ -31,6 +31,15 @@ impl PyPaymentOutput { Self(PaymentOutput::new(address.into(), amount)) } + /// Create a new Payment Output bound to a covenant. + /// + /// Args: + /// address: The address to send this output to. + /// amount: The amount, in sompi, to send on this output. + /// covenant: The covenant binding to attach to this output. + /// + /// Returns: + /// PaymentOutput: A new PaymentOutput instance. #[staticmethod] fn with_covenant(address: PyAddress, amount: u64, covenant: PyCovenantBinding) -> Self { Self(PaymentOutput::with_covenant( diff --git a/src/wallet/core/wallet.rs b/src/wallet/core/wallet.rs index 8fe3d692..5aade35f 100644 --- a/src/wallet/core/wallet.rs +++ b/src/wallet/core/wallet.rs @@ -81,6 +81,13 @@ impl Inner { } } +/// A managed Kaspa wallet with persistent encrypted on-disk storage. +/// +/// The SDK's high-level wallet. Provides encrypted storage for keys and +/// account metadata, multi-account management (BIP32 and keypair accounts), +/// address derivation and discovery, built-in send, transfer, and sweep +/// flows, transaction history tracking, and an event bus for chain +/// notifications (balance, maturity, reorg). #[gen_stub_pyclass] #[pyclass(name = "Wallet")] #[derive(Clone)]