;
/// Set a value in the local cache.
///
- /// The default expiration time is 7 days. Use `cache_set_expiration` to set a custom expiration
- /// time.
+ /// This method sets a value in the local cache with the default expiration time of 7 days.
+ /// To set a custom expiration time, use `cache_set_expiration`.
/// Values stored in cache can only be read in query functions.
+ /// Always returns `Ok(())` if it is called from a transaction context.
+ ///
+ /// # Arguments
+ ///
+ /// * `key`: The key used to identify the value in the cache.
+ /// * `value`: The value to be stored in the cache.
+ ///
+ /// # Returns
///
- /// Alwasy returns `Ok(())` if it is called from a command context.
+ /// * `Result<(), StorageQuotaExceeded>` - `Ok(())` or `Err(StorageQuotaExceeded)` if the storage quota is exceeded.
+ ///
+ ///
+ /// Warning:
+ /// The cache is not guaranteed to be persistent. It may be cleared at any time due
+ /// to various reasons:
+ ///
+ /// - The cached item is expired.
+ /// - The entire cache in pRuntime is full and a new value needs to be stored (either from the contract itself or
+ /// other contracts).
+ /// - The worker is restarted.
+ ///
+ ///
+ /// In order to use cache, the contract need to be staked via the phala on-chain API `PhatTokenomic::adjust_stake`.
+ /// All contracts will share the 20MB cache storage by the ratio of stake.
+ ///
+ /// # Example
+ ///
+ /// ```ignore
+ /// let key = b"my key";
+ /// let value = b"my value";
+ /// let result = pink::ext().cache_set(key, value);
+ /// ```
+ ///
+ /// # Availability
+ /// any contract | query | transaction
#[ink(extension = 6, handle_status = true)]
fn cache_set(key: &[u8], value: &[u8]) -> Result<(), StorageQuotaExceeded>;
/// Set the expiration time of a value in the local cache.
///
- /// Arguments:
- /// - `key`: The key of the value to set the expiration time for.
- /// - `expire`: The expiration time from now in seconds.
+ /// This method sets the expiration time for a given key in the local cache.
+ ///
+ /// # Arguments
+ ///
+ /// * `key`: The key of the value to set the expiration time for.
+ /// * `expire`: The expiration time from now in seconds.
+ ///
+ /// # Example
+ ///
+ /// ```ignore
+ /// let key = b"my key";
+ /// let expire = 60; // 1 minute
+ /// pink::ext().cache_set_expiration(key, expire);
+ /// ```
+ ///
+ /// # Availability
+ /// any contract | query | transaction
#[ink(extension = 7, handle_status = false)]
fn cache_set_expiration(key: &[u8], expire: u64);
/// Get a value from the local cache.
///
- /// Only for query functions. Always returns `None` if it is called from a command context.
+ /// This method retrieves a value from the local cache. It can only be used in query functions.
+ /// If called from a transaction context, it will always return `None`.
+ ///
+ /// # Arguments
+ ///
+ /// * `key`: The key used to identify the value in the cache.
+ ///
+ /// # Returns
+ ///
+ /// * `Option>` - The value from the cache as a byte vector wrapped in an Option,
+ /// or `None` if the value does not exist or called in transaction.
+ ///
+ /// # Example
+ ///
+ /// ```ignore
+ /// let key = b"my key";
+ /// let value = pink::ext().cache_get(key);
+ /// ```
+ ///
+ /// # Availability
+ /// any contract | query
#[ink(extension = 8, handle_status = false)]
fn cache_get(key: &[u8]) -> Option>;
/// Remove a value from the local cache.
///
- /// Returns the removed value if it existed. Always returns `None` if it is called from a
- /// command context.
+ /// This method removes a value from the local cache and returns the removed value if it existed.
+ /// If called from a transaction context, it will always return `None`.
+ ///
+ /// # Arguments
+ ///
+ /// * `args`: The key used to identify the value in the cache.
+ ///
+ /// # Returns
+ ///
+ /// * `Option>` - The removed value as a byte vector wrapped in an Option
+ /// or `None` if the value did not exist or called in transaction.
+ ///
+ /// # Availability
+ /// any contract | query | transaction
#[ink(extension = 9, handle_status = false)]
fn cache_remove(args: &[u8]) -> Option>;
- /// Print log message.
+ /// Log a message.
+ ///
+ /// This method logs a message at a given level.
+ ///
+ /// The logs would be shown in the worker log file. Additionally, if a log server
+ /// contract has been deployed in the cluster, the logs would be sent to the log server.
+ /// Users can query the logs via the log server API.
+ ///
+ /// # Arguments
+ ///
+ /// * `level`: The level of the log message.
+ /// * `message`: The message to be logged.
+ ///
+ /// # Example
+ ///
+ /// ```ignore
+ /// let level = 1;
+ /// let message = "Hello, world!";
+ /// pink::ext().log(level, message);
+ /// ```
+ ///
+ /// # Note
+ /// This is the low-level method for logging. It is recommended to use shortcuts macros below instead:
+ ///
+ /// - [`debug!`]
+ /// - [`info!`]
+ /// - [`warn!`]
+ /// - [`error!`]
+ ///
+ /// # Availability
+ /// any contract | query | transaction
#[ink(extension = 10, handle_status = false)]
fn log(level: u8, message: &str);
- /// Get random bytes, for query only
+ /// Get random bytes.
+ ///
+ /// This method generates a vector of random bytes of a given length. It returns random bytes
+ /// generated by hardware RNG. So it is not deterministic and only available in a query context.
+ ///
+ /// # Note
+ /// It always returns an empty vec![] when called in a transaction.
+ ///
+ ///
+ /// # Arguments
+ ///
+ /// * `length`: The length of the random bytes vector.
+ ///
+ /// # Returns
+ ///
+ /// * `Vec` - A vector of random bytes of the given length.
+ ///
+ /// # Example
+ ///
+ /// ```ignore
+ /// let length = 32;
+ /// let random_bytes = pink::ext().getrandom(length);
+ /// ```
+ ///
+ /// # Availability
+ /// any contract | query only
#[ink(extension = 11, handle_status = false)]
fn getrandom(length: u8) -> Vec;
- /// Check if it is running in a Command context.
+ /// Check if it is running in a transaction context.
+ ///
+ /// # Returns
+ ///
+ /// * `bool` - `true` if it is running in a transaction context, `false` if in query.
+ ///
+ /// # Availability
+ /// any contract | query | transaction
#[allow(clippy::wrong_self_convention)]
#[ink(extension = 12, handle_status = false)]
fn is_in_transaction() -> bool;
+ /// Sign a prehashed message with a given key.
+ ///
+ /// This method uses the given key and prehashed message to create a ECDSA signature.
+ ///
+ /// # Arguments
+ ///
+ /// * `key`: The private key used for signing the message.
+ /// * `message_hash`: The prehashed message to be signed.
+ ///
+ /// # Returns
+ ///
+ /// * `EcdsaSignature` - The signature of the message.
+ ///
+ /// # Example
+ ///
+ /// ```ignore
+ /// let key = [0u8; 32]; // replace with actual key
+ /// let message_hash = Hash::zero(); // replace with actual hash
+ /// let signature = pink::ext().ecdsa_sign_prehashed(&key, message_hash);
+ /// ```
+ ///
+ /// # Availability
+ /// any contract | query | transaction
#[ink(extension = 13, handle_status = false)]
fn ecdsa_sign_prehashed(key: &[u8], message_hash: Hash) -> EcdsaSignature;
+ /// Verify a prehashed ECDSA signature.
+ ///
+ /// This method verifies a prehashed ECDSA signature given the signature, prehashed message, and public key.
+ ///
+ /// # Arguments
+ ///
+ /// * `signature`: The ECDSA digital signature to verify.
+ /// * `message_hash`: The prehashed original message that was signed.
+ /// * `pubkey`: The public key associated with the private key that signed the message.
+ ///
+ /// # Returns
+ ///
+ /// * `bool` - `true` if the signature is valid, `false` otherwise.
+ ///
+ /// # Example
+ ///
+ /// ```ignore
+ /// let signature = EcdsaSignature::default(); // replace with actual signature
+ /// let message_hash = Hash::zero(); // replace with actual hash
+ /// let pubkey = EcdsaPublicKey::default(); // replace with actual pubkey
+ /// let is_valid = pink::ext().ecdsa_verify_prehashed(signature, message_hash, pubkey);
+ /// ```
+ ///
+ /// # Availability
+ /// any contract | query | transaction
#[ink(extension = 14, handle_status = false)]
fn ecdsa_verify_prehashed(
signature: EcdsaSignature,
message_hash: Hash,
pubkey: EcdsaPublicKey,
) -> bool;
- /// Get the contract id of the preinstalled pink-system
+
+ /// Get the contract id of the preinstalled system contract.
+ ///
+ /// # Availability
+ /// any contract | query | transaction
#[ink(extension = 15, handle_status = false)]
fn system_contract_id() -> AccountId;
- /// Get (total, free) balance of given contract
+ /// Get balance of a given address.
+ ///
+ /// # Arguments
+ ///
+ /// * `account`: The `AccountId` of the contract.
+ ///
+ /// # Returns
+ ///
+ /// * `(Balance, Balance)` - The total and free balance of a given contract.
+ ///
+ /// # Availability
+ /// any contract | query | transaction
#[ink(extension = 16, handle_status = false)]
fn balance_of(account: AccountId) -> (Balance, Balance);
- /// Get worker public key. Query only.
+ /// Get the public key of the worker running this query.
+ ///
+ /// # Returns
+ ///
+ /// * `crate::EcdhPublicKey` - The public key of the worker.
+ ///
+ /// # Availability
+ /// any contract | query only
#[ink(extension = 17, handle_status = false)]
fn worker_pubkey() -> crate::EcdhPublicKey;
- /// Get current millis since unix epoch from the OS. (Query only)
+ /// Get current millis since Unix epoch.
+ ///
+ /// This method returns the current time as milliseconds since the Unix epoch from the OS.
+ ///
+ /// # Returns
+ ///
+ /// * `u64` - The current time as milliseconds since the Unix epoch from the OS.
+ ///
+ /// # Note
+ /// Because this method uses the OS time, it is not deterministic and may be manipulated by compromised OS.
+ ///
+ /// # Example
+ ///
+ /// ```ignore
+ /// let current_millis = pink::ext().untrusted_millis_since_unix_epoch();
+ /// ```
+ ///
+ /// # Availability
+ /// any contract | query only
#[ink(extension = 18, handle_status = false)]
fn untrusted_millis_since_unix_epoch() -> u64;
/// Check whether the code exists in the cluster storage.
+ ///
+ /// # Returns
+ ///
+ /// * `bool` - `true` if the code exists, `false` otherwise.
+ ///
+ /// # Example
+ ///
+ /// ```ignore
+ /// let code_hash = Hash::zero(); // replace with actual code hash
+ /// let exists = pink::ext().code_exists(code_hash, false);
+ /// ```
+ ///
+ /// # Availability
+ /// any contract | query | transaction
#[ink(extension = 19, handle_status = false)]
fn code_exists(code_hash: Hash, sidevm: bool) -> bool;
- /// This loads the latest system contract code from chain storage to the cluster storage.
+ /// Import the latest system contract code from chain storage to the cluster storage.
+ ///
+ /// # Returns
+ ///
+ /// * `Option` - The code hash of the latest system contract code, or `None` if the import failed.
+ ///
+ /// # Example
///
- /// Returns the code hash of the latest system contract code.
+ /// ```ignore
+ /// let payer = AccountId::default(); // replace with actual payer id
+ /// let code_hash = pink::ext().import_latest_system_code(payer);
+ /// ```
+ ///
+ /// # Availability
+ /// system only | query | transaction
#[ink(extension = 20, handle_status = false)]
fn import_latest_system_code(payer: AccountId) -> Option;
- /// Get the version of the current contract runtime in this cluster.
+ /// Get the version of the current contract runtime.
+ ///
+ /// # Returns
+ ///
+ /// * `(u32, u32)` - The version of the current contract runtime in this cluster as a tuple (major, minor).
+ ///
+ /// # Example
+ ///
+ /// ```ignore
+ /// let (major, minor) = pink::ext().runtime_version();
+ /// ```
+ ///
+ /// # Availability
+ /// any contract | query | transaction
#[ink(extension = 21, handle_status = false)]
fn runtime_version() -> (u32, u32);
- /// Batch http request
+ /// Batch HTTP request.
+ ///
+ /// This method sends a batch of HTTP requests with a given timeout and returns the results.
+ ///
+ /// # Arguments
+ ///
+ /// * `requests`: A vector of `HttpRequest` structs containing all the details for the HTTP requests.
+ /// * `timeout_ms`: The timeout for the batch request in milliseconds.
+ ///
+ /// # Returns
+ ///
+ /// * `BatchHttpResult` - A vector of response to eahch HTTP requests.
+ ///
+ /// # Example
+ ///
+ /// ```ignore
+ /// let requests = vec![
+ /// HttpRequest::new("https://httpbin.org/get",
+ /// "GET",
+ /// Default::default(),
+ /// Default::default(),
+ /// ),
+ /// HttpRequest::new("https://httpbin.org/post",
+ /// "POST",
+ /// Default::default(),
+ /// b"Hello, world!".to_vec(),
+ /// ),
+ /// ];
+ /// let result = pink::ext().batch_http_request(requests, 5000);
+ /// ```
#[ink(extension = 22, handle_status = true)]
fn batch_http_request(requests: Vec, timeout_ms: u64) -> BatchHttpResult;
}
diff --git a/crates/pink/pink-extension/src/chain_extension/http_request.rs b/crates/pink/pink-extension/src/chain_extension/http_request.rs
index 24cfbe0d04..a2010cd5bf 100644
--- a/crates/pink/pink-extension/src/chain_extension/http_request.rs
+++ b/crates/pink/pink-extension/src/chain_extension/http_request.rs
@@ -12,6 +12,23 @@ pub struct HttpRequest {
pub body: Vec,
}
+impl HttpRequest {
+ /// Create a new http request.
+ pub fn new(
+ url: impl Into,
+ method: impl Into,
+ headers: Vec<(String, String)>,
+ body: Vec,
+ ) -> Self {
+ Self {
+ url: url.into(),
+ method: method.into(),
+ headers,
+ body,
+ }
+ }
+}
+
#[derive(scale::Encode, scale::Decode)]
#[cfg_attr(feature = "std", derive(scale_info::TypeInfo))]
pub struct HttpResponse {
@@ -126,8 +143,8 @@ macro_rules! http_req {
/// Make a simple HTTP GET request
///
/// # Arguments
-/// url: The URL to GET
-/// headers: The headers to send with the request
+/// - url: The URL to GET
+/// - headers: The headers to send with the request
///
/// # Examples
///
@@ -156,9 +173,9 @@ macro_rules! http_get {
/// Make a simple HTTP POST request
///
/// # Arguments
-/// url: The URL to POST
-/// data: The payload to POST
-/// headers: The headers to send with the request
+/// - url: The URL to POST
+/// - data: The payload to POST
+/// - headers: The headers to send with the request
///
/// # Examples
///
@@ -187,9 +204,9 @@ macro_rules! http_post {
/// Make a simple HTTP PUT request
///
/// # Arguments
-/// url: The destination URL
-/// data: The payload to PUT
-/// headers: The headers to send with the request
+/// - url: The destination URL
+/// - data: The payload to PUT
+/// - headers: The headers to send with the request
///
/// # Examples
///
diff --git a/crates/pink/pink-extension/src/lib.rs b/crates/pink/pink-extension/src/lib.rs
index 94f90e8433..b08c4fcbe1 100644
--- a/crates/pink/pink-extension/src/lib.rs
+++ b/crates/pink/pink-extension/src/lib.rs
@@ -1,5 +1,6 @@
#![cfg_attr(not(feature = "std"), no_std)]
#![cfg_attr(not(feature = "std"), feature(alloc_error_handler))]
+#![doc = include_str!("../README.md")]
extern crate alloc;
@@ -61,9 +62,11 @@ pub struct OspMessage {
pub remote_pubkey: Option,
}
+/// Hook points defined in the runtime.
#[derive(Encode, Decode, Debug, Clone)]
#[cfg_attr(feature = "std", derive(scale_info::TypeInfo))]
pub enum HookPoint {
+ /// When all events in a block are processed.
OnBlockEnd,
}
@@ -72,6 +75,11 @@ pub enum HookPoint {
#[cfg_attr(feature = "std", derive(scale_info::TypeInfo))]
pub enum PinkEvent {
/// Set contract hook
+ ///
+ /// Please do not use this event directly, use [`set_hook()`] instead.
+ ///
+ /// # Availability
+ /// System contract
#[codec(index = 2)]
SetHook {
/// The event to hook
@@ -84,6 +92,11 @@ pub enum PinkEvent {
gas_limit: u64,
},
/// Deploy a sidevm instance to given contract instance
+ ///
+ /// Please do not use this event directly, use [`deploy_sidevm_to()`] instead.
+ ///
+ /// # Availability
+ /// System contract
#[codec(index = 3)]
DeploySidevmTo {
/// The target contract address
@@ -92,27 +105,60 @@ pub enum PinkEvent {
code_hash: Hash,
},
/// Push a message to the associated sidevm instance.
+ ///
+ /// Please do not use this event directly, use [`push_sidevm_message()`] instead.
+ ///
+ /// # Availability
+ /// Any contract
#[codec(index = 4)]
SidevmMessage(Vec),
- /// CacheOperation
+ /// Instructions to manipulate the cache. Including set, remove and set expiration.
+ ///
+ /// # Availability
+ /// Any contract
#[codec(index = 5)]
CacheOp(CacheOp),
- /// Stop the side VM instance if it is running.
+ /// Stop the side VM instance associated with the caller contract if it is running.
+ ///
+ /// Please do not use this event directly, use [`force_stop_sidevm()`] instead.
+ ///
+ /// # Availability
+ /// Any contract
#[codec(index = 6)]
StopSidevm,
- /// Force stop the side VM instance if it is running.
+ /// Force stop the side VM instance associated with the given contract if it is running.
+ ///
+ /// Please do not use this event directly, use [`stop_sidevm_at()`] instead.
+ ///
+ /// # Availability
+ /// System contract
#[codec(index = 7)]
ForceStopSidevm {
/// The target contract address
contract: AccountId,
},
/// Set the log handler contract for current cluster.
+ ///
+ /// Please do not use this event directly, use [`set_log_handler()`] instead.
+ ///
+ /// # Availability
+ /// System contract
#[codec(index = 8)]
SetLogHandler(AccountId),
- /// Set the weight of contract used to schedule queries and sidevm vruntime
+ /// Set the weight of contract used to schedule queries and sidevm virtual runtime
+ ///
+ /// Please do not use this event directly, use [`set_contract_weight()`] instead.
+ ///
+ /// # Availability
+ /// System contract
#[codec(index = 9)]
SetContractWeight { contract: AccountId, weight: u32 },
/// Upgrade the runtime to given version
+ ///
+ /// Please do not use this event directly, use [`upgrade_runtime()`] instead.
+ ///
+ /// # Availability
+ /// System contract
#[codec(index = 10)]
UpgradeRuntimeTo { version: (u32, u32) },
}
@@ -147,11 +193,15 @@ impl PinkEvent {
}
}
+/// Instructions to manipulate the cache.
#[derive(Encode, Decode, Debug, Clone)]
#[cfg_attr(feature = "std", derive(scale_info::TypeInfo))]
pub enum CacheOp {
+ /// Set a key-value pair in the cache.
Set { key: Vec, value: Vec },
+ /// Set the expiration of a key-value pair in the cache.
SetExpiration { key: Vec, expiration: u64 },
+ /// Remove a key-value pair from the cache.
Remove { key: Vec },
}
@@ -183,8 +233,25 @@ impl PinkEvent {
}
}
-/// Turn on on_block_end feature and set it's selector
+/// Sets a hook receiver for a given hook point.
///
+/// A hook is a mechanism that allows certain actions to be triggered when a specific situation arises.
+/// When the situation corresponding to the hook point occurs, the runtime will call the receiver contract
+/// using the specified selector.
+///
+/// # Supported Hook Points
+/// - `OnBlockEnd`: The receiver contract will be invoked once all events in a Phala chain block have been processed.
+///
+/// # Arguments
+///
+/// * `hook`: The hook point for which the receiver is set.
+/// * `contract`: The AccountId of the contract to be called when the hook is triggered.
+/// * `selector`: The function selector to be used when calling the receiver contract.
+/// * `gas_limit`: The maximum amount of gas that can be used when calling the receiver contract.
+///
+/// Note: The cost of the execution would be charged to the contract itself.
+///
+/// This api is only available for the system contract. User contracts should use `System::set_hook` instead.
pub fn set_hook(hook: HookPoint, contract: AccountId, selector: u32, gas_limit: u64) {
emit_event::(PinkEvent::SetHook {
hook,
@@ -194,15 +261,28 @@ pub fn set_hook(hook: HookPoint, contract: AccountId, selector: u32, gas_limit:
})
}
-/// Start a SideVM instance
+/// Starts a SideVM instance with the provided code hash.
+///
+/// The calling contract must be authorized by the `SidevmOperation` driver contract.
+///
+/// If the code corresponding to the provided hash hasn't been uploaded to the cluster storage yet,
+/// it will create an empty SideVM instance. This instance will wait for the code to be uploaded
+/// via `prpc::UploadSidevmCode`.
+///
+///# Arguments
+///
+///* `code_hash`: The hash of the code to be used for starting the SideVM instance.
+///
+///# Returns
+///
+/// A `Result` indicating success or failure, specifically a `system::DriverError` in case of failure.
pub fn start_sidevm(code_hash: Hash) -> Result<(), system::DriverError> {
let driver =
crate::system::SidevmOperationRef::instance().ok_or(system::Error::DriverNotFound)?;
driver.deploy(code_hash)
}
-/// Deploy a SideVM instance to a given contract.
-/// The caller must be the system contract.
+/// Deploy a SideVM instance to a given contract. (system only)
pub fn deploy_sidevm_to(contract: AccountId, code_hash: Hash) {
emit_event::(PinkEvent::DeploySidevmTo {
contract,
@@ -210,8 +290,7 @@ pub fn deploy_sidevm_to(contract: AccountId, code_hash: Hash) {
});
}
-/// Stop a SideVM instance running at given contract address.
-/// The caller must be the system contract.
+/// Stop a SideVM instance running at given contract address. (system only)
pub fn stop_sidevm_at(contract: AccountId) {
emit_event::(PinkEvent::ForceStopSidevm { contract });
}
@@ -224,27 +303,61 @@ pub fn force_stop_sidevm() {
emit_event::(PinkEvent::StopSidevm)
}
-/// Push a message to the associated sidevm instance.
+/// Pushes a message to the associated SideVM instance.
+///
+/// Note: There is no guarantee that the message will be received by the SideVM instance.
+/// The message may be dropped due to several reasons:
+///
+/// - The SideVM instance is not currently running.
+/// - The SideVM instance is running, but the message queue is full. This may occur when the SideVM
+/// instance is busy processing other messages.
+///
+///# Arguments
+///
+///* `message`: The message to be pushed to the SideVM instance.
pub fn push_sidevm_message(message: Vec) {
emit_event::(PinkEvent::SidevmMessage(message))
}
-/// Set the log handler contract of current cluster
+/// Set the log handler contract of current cluster. (system only)
pub fn set_log_handler(contract: AccountId) {
emit_event::(PinkEvent::SetLogHandler(contract))
}
-/// Set the weight of contract used to schedule queries and sidevm vruntime
+/// Set the weight of contract used to schedule queries and sidevm virtual runtime. (system only)
pub fn set_contract_weight(contract: AccountId, weight: u32) {
emit_event::(PinkEvent::SetContractWeight { contract, weight });
}
-/// Upgrade the runtime to given version
+/// Upgrade the pink runtime to given version. (system only)
+///
+/// Note: pRuntime would exit if the version is not supported.
pub fn upgrade_runtime(version: (u32, u32)) {
emit_event::(PinkEvent::UpgradeRuntimeTo { version });
}
-/// Pink defined environment. Used this environment to access the phat contract runtime features.
+/// Pink defined environment. This environment is used to access the phat contract extended runtime features.
+///
+/// # Example
+/// ```
+/// #[ink::contract(env = PinkEnvironment)]
+/// mod my_contract {
+/// use pink_extension::PinkEnvironment;
+/// #[ink(storage)]
+/// pub struct MyContract {}
+/// impl MyContract {
+/// #[ink(constructor)]
+/// pub fn new() -> Self {
+/// Self {}
+/// }
+/// #[ink(message)]
+/// pub fn my_message(&self) {
+/// // Access the pink environment.
+/// let _pink_version = self.env().extension().runtime_version();
+/// }
+/// }
+/// }
+/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "std", derive(scale_info::TypeInfo))]
pub enum PinkEnvironment {}
@@ -261,6 +374,7 @@ impl Environment for PinkEnvironment {
type ChainExtension = chain_extension::PinkExt;
}
+/// Returns the PinkEnvironment.
pub fn env() -> EnvAccess<'static, PinkEnvironment> {
Default::default()
}
diff --git a/crates/pink/pink-extension/src/logger.rs b/crates/pink/pink-extension/src/logger.rs
index 89f1f785fe..ed156ebc30 100644
--- a/crates/pink/pink-extension/src/logger.rs
+++ b/crates/pink/pink-extension/src/logger.rs
@@ -34,37 +34,58 @@ pub fn log(level: Level, args: Arguments<'_>) {
Logger.log(&record);
}
-/// Same as log::log!
+/// The `log!` macro allows you to log messages with specific logging levels in pink contract.
+///
+/// It is a flexible macro that uses a provided log level (trace, debug, info, warn, error),
+/// followed by a format string and an optional list of arguments to generate the final log message.
#[macro_export]
macro_rules! log {
($level: expr, $($arg:tt)+) => {{ $crate::logger::log($level, ::core::format_args!($($arg)+)) }}
}
-/// Same as log::error!
+/// Same as `info!` but at Error level.
#[macro_export(local_inner_macros)]
macro_rules! error {
($($arg:tt)+) => {{ log!($crate::logger::Level::Error, $($arg)+) }}
}
-/// Same as log::warn!
+/// Same as `info!` but at Warn level.
#[macro_export(local_inner_macros)]
macro_rules! warn {
($($arg:tt)+) => {{ log!($crate::logger::Level::Warn, $($arg)+) }}
}
-/// Same as log::info!
+/// Macro `info!` logs messages at the Info level in pink contract.
+///
+/// This macro is used to log information that would be helpful to understand the general flow
+/// of the system's execution. It is similar to `log::info`, but it is specifically designed
+/// to work within the pink contract environment.
+///
+/// # Examples
+///
+/// Basic usage:
+///
+/// ```ignore
+/// use pink_extension as pink;
+/// pink::info!("This is an information message.");
+/// let answer = 42;
+/// pink::info!("The answer is {}.", answer);
+/// ```
+///
+/// The above example would log "This is an information message." and
+/// "The answer is 42." at the Info level.
#[macro_export(local_inner_macros)]
macro_rules! info {
($($arg:tt)+) => {{ log!($crate::logger::Level::Info, $($arg)+) }}
}
-/// Same as log::debug!
+/// Same as `info!` but at Debug level.
#[macro_export(local_inner_macros)]
macro_rules! debug {
($($arg:tt)+) => {{ log!($crate::logger::Level::Debug, $($arg)+) }}
}
-/// Same as log::trace!
+/// Same as `info!` but at Trace level.
#[macro_export(local_inner_macros)]
macro_rules! trace {
($($arg:tt)+) => {{ log!($crate::logger::Level::Trace, $($arg)+) }}
diff --git a/crates/pink/pink-extension/src/system.rs b/crates/pink/pink-extension/src/system.rs
index f06b166293..48775de94b 100644
--- a/crates/pink/pink-extension/src/system.rs
+++ b/crates/pink/pink-extension/src/system.rs
@@ -41,52 +41,65 @@ pub use this_crate::VersionTuple;
/// The pink system contract interface.
///
-/// A system contract would be instantiated whenever a cluster is created.
+/// The system contract, instantiated with each cluster creation, manages access permissions to
+/// the privileged chain extension functions and pink events. Some of these functions or events
+/// are exclusive to the system contract. User contracts wishing to call these functions or
+/// emit these events must first request the system contract, which then checks the permissions
+/// to either execute or reject the request.
#[pink::system]
#[ink::trait_definition(namespace = "pink_system")]
pub trait System {
- /// The version of the system. Can be used to determine the api ability.
+ /// Returns the system contract version, indicating its API capabilities.
+ ///
+ /// # Example
+ /// ```no_run
+ /// use pink_extension::system::SystemRef;
+ /// let (major, minor, patch) = SystemRef::instance().version();
+ /// ```
#[ink(message, selector = 0x87c98a8d)]
fn version(&self) -> VersionTuple;
- /// Grant an address the administrator role.
+
+ /// Grants the administrator role to an address. Administrator contracts can set drivers,
+ /// deploy sidevm, etc.
///
- /// The caller must be the owner of the cluster.
+ /// Must be called by the cluster owner.
#[ink(message)]
fn grant_admin(&mut self, contract_id: AccountId) -> Result<()>;
- /// Check if an address is an administrator
+ /// Checks if an address is an administrator.
#[ink(message)]
fn is_admin(&self, contract_id: AccountId) -> bool;
- /// Set a contract as a driver for `name`.
+ /// Marks a contract as a driver for a given name, retrievable via `get_driver` or `get_driver2`.
+ /// The caller must be the cluster owner or an administrator. Any valid string can be a name.
+ /// There are predefined names used by the Phat Contract system.
///
- /// The caller must be the owner of the cluster or an administrator.
+ /// There are some predefined names that are used by the Phat Contract system:
+ /// - `PinkLogger`: The contract that with a sidevm instance that collect the logs and events
+ /// emitted by the ink! contracts in current cluster.
+ /// - `ContractDeposit`: The contract that implements the `trait ContractDeposit` which talks
+ /// to the pallet PhatTokenomic on Phala chain.
#[ink(message)]
fn set_driver(&mut self, name: String, contract_id: AccountId) -> Result<()>;
- /// Get driver contract id for `name`.
+ /// Retrieves the driver contract id for a given name.
#[ink(message)]
fn get_driver(&self, name: String) -> Option;
- /// Get driver contract id for `name` and the set block number.
+ /// Retrieves the driver contract id and the set block number for a given name.
#[ink(message)]
fn get_driver2(&self, name: String) -> Option<(crate::BlockNumber, AccountId)>;
- /// Deploy a sidevm instance attached to a given contract.
- ///
- /// The caller must be an administrator.
+ /// Deploys a sidevm instance attached to a contract. Must be called by an administrator.
#[ink(message)]
fn deploy_sidevm_to(&self, contract_id: AccountId, code_hash: Hash) -> Result<()>;
- /// Stop a sidevm instance attached to a given contract.
- ///
- /// The caller must be an administrator.
+ /// Stops a sidevm instance attached to a contract. Must be called by an administrator.
#[ink(message)]
fn stop_sidevm_at(&self, contract_id: AccountId) -> Result<()>;
- /// Set block hook, such as OnBlockEnd, for given contract
- ///
- /// The caller must be an administrator.
+ /// Sets a block hook for a contract. Must be called by an administrator.
+ /// Note: This feature is deprecated and will be removed in the future.
#[ink(message)]
fn set_hook(
&mut self,
@@ -96,44 +109,43 @@ pub trait System {
gas_limit: u64,
) -> Result<()>;
- /// Set weight of the contract for query requests and sidevm scheduling.
- ///
- /// Higher weight would let the contract to get more resource.
+ /// Sets the contract weight for query requests and sidevm scheduling.
+ /// A higher weight allows the contract to access more resources.
#[ink(message)]
fn set_contract_weight(&self, contract_id: AccountId, weight: u32) -> Result<()>;
- /// Return the total balance of given account
+ /// Returns the total balance of a given account.
#[ink(message)]
fn total_balance_of(&self, account: AccountId) -> Balance;
- /// Return the free balance of given account
+ /// Returns the free balance of a given account.
#[ink(message)]
fn free_balance_of(&self, account: AccountId) -> Balance;
- /// Upgrade the system contract to the latest version.
+ /// Upgrades the system contract to the latest version.
#[ink(message)]
fn upgrade_system_contract(&mut self) -> Result<()>;
- /// Do the upgrade condition checks and state migration if necessary.
- ///
- /// This function is called by the system contract itself on the new version
- /// of code in the upgrading process.
+ /// Performs upgrade condition checks and state migration if necessary.
+ /// Called by the system contract on the new code version during an upgrade process.
#[ink(message)]
fn do_upgrade(&self, from_version: VersionTuple) -> Result<()>;
- /// Upgrade the contract runtime
+ /// Upgrades the contract runtime.
#[ink(message)]
fn upgrade_runtime(&mut self, version: (u32, u32)) -> Result<()>;
- /// Check if the code is already uploaded to the cluster with given code hash.
+ /// Checks if the code with a given hash is already uploaded to the cluster.
#[ink(message)]
fn code_exists(&self, code_hash: Hash, code_type: CodeType) -> bool;
- /// Get the current code hash of given contract.
+ /// Retrieves the current code hash of a given contract.
#[ink(message)]
fn code_hash(&self, account: AccountId) -> Option;
- /// Get the history of given driver.
+ /// Retrieves the history of a given driver, returning a vector of
+ /// (block_number, contract_id) tuples where the block number is the
+ /// block number when the driver is set.
#[ink(message)]
fn driver_history(&self, name: String) -> Option>;
}
diff --git a/standalone/pruntime/Cargo.lock b/standalone/pruntime/Cargo.lock
index fe1bcc20a8..657d1ac278 100644
--- a/standalone/pruntime/Cargo.lock
+++ b/standalone/pruntime/Cargo.lock
@@ -4869,7 +4869,7 @@ dependencies = [
[[package]]
name = "pink-extension"
-version = "0.4.3"
+version = "0.4.4"
dependencies = [
"ink",
"log",
@@ -4882,7 +4882,7 @@ dependencies = [
[[package]]
name = "pink-extension-macro"
-version = "0.4.2"
+version = "0.4.4"
dependencies = [
"heck 0.4.0",
"ink_ir",