gbuiltin_staking/
lib.rs

1// This file is part of Gear.
2
3// Copyright (C) 2021-2025 Gear Technologies Inc.
4// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
5
6// This program is free software: you can redistribute it and/or modify
7// it under the terms of the GNU General Public License as published by
8// the Free Software Foundation, either version 3 of the License, or
9// (at your option) any later version.
10
11// This program is distributed in the hope that it will be useful,
12// but WITHOUT ANY WARRANTY; without even the implied warranty of
13// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14// GNU General Public License for more details.
15
16// You should have received a copy of the GNU General Public License
17// along with this program. If not, see <https://www.gnu.org/licenses/>.
18
19//! Helper crate defining Gear built-in actors communication protocol.
20//!
21//! This crate defines a set of types that contracts can use to interact
22//! with the so-called "builtin" actors - that is the actors that are defined
23//! for any Gear runtime and provide an API for the applications to build on top
24//! of some blockchain logic like staking, governance, etc.
25
26//! For a builtin actor to process a message, it should be able to decode its
27//! payload into one of the supported message types.
28//!
29//! # Examples
30//!
31//! The following example shows how a contract can send a message to a builtin actor
32//! (specifically, a staking actor) to bond some `value` to self as the controller
33//! so that the contract can later use the staking API to nominate validators.
34//!
35//! ```ignore
36//! use gstd::{msg, ActorId};
37//! use gbuiltins::staking::{Request, RewardAccount};
38//! use parity_scale_codec::Encode;
39//!
40//! const BUILTIN_ADDRESS: ActorId = ActorId::new(hex_literal::hex!(
41//!     "77f65ef190e11bfecb8fc8970fd3749e94bed66a23ec2f7a3623e785d0816761"
42//! ));
43//!
44//! #[gstd::async_main]
45//! async fn main() {
46//!     let value = msg::value();
47//!     let payee: RewardAccount = RewardAccount::Program;
48//!     let payload = Request::Bond { value, payee }.encode();
49//!     let _ = msg::send_bytes_for_reply(BUILTIN_ADDRESS, &payload[..], 0, 0)
50//!         .expect("Error sending message")
51//!         .await;
52//! }
53//! # fn main() {}
54//! ```
55
56#![no_std]
57
58extern crate alloc;
59
60use alloc::vec::Vec;
61use gprimitives::ActorId;
62use parity_scale_codec::{Decode, Encode};
63use scale_info::TypeInfo;
64
65/// Type that should be used to create a message to the staking built-in actor.
66///
67/// A `partial` mirror of the staking pallet interface. Not all extrinsics
68/// are supported, more can be added as needed for real-world use cases.
69#[derive(Debug, Clone, Eq, PartialEq, Encode, Decode, TypeInfo)]
70pub enum Request {
71    /// Bond up to the `value` from the sender to self as the controller.
72    #[codec(index = 0)]
73    Bond { value: u128, payee: RewardAccount },
74
75    /// Add up to the `value` to the sender's bonded amount.
76    #[codec(index = 1)]
77    BondExtra { value: u128 },
78
79    /// Unbond up to the `value` to allow withdrawal after undonding period.
80    #[codec(index = 2)]
81    Unbond { value: u128 },
82
83    /// Withdraw unbonded chunks for which undonding period has elapsed.
84    #[codec(index = 3)]
85    WithdrawUnbonded { num_slashing_spans: u32 },
86
87    /// Add sender as a nominator of `targets` or update the existing targets.
88    #[codec(index = 4)]
89    Nominate { targets: Vec<ActorId> },
90
91    /// Declare intention to `temporarily` stop nominating while still having funds bonded.
92    #[codec(index = 5)]
93    Chill,
94
95    /// Request stakers payout for the given era.
96    #[codec(index = 6)]
97    PayoutStakers { validator_stash: ActorId, era: u32 },
98
99    /// Rebond a portion of the sender's stash scheduled to be unlocked.
100    #[codec(index = 7)]
101    Rebond { value: u128 },
102
103    /// Set the reward destination.
104    #[codec(index = 8)]
105    SetPayee { payee: RewardAccount },
106
107    /// Get the active era.
108    #[codec(index = 9)]
109    ActiveEra,
110}
111
112/// An account where the rewards should accumulate on.
113///
114/// A "mirror" of the staking pallet's `RewardDestination` enum.
115#[derive(Debug, Clone, Copy, Eq, PartialEq, Encode, Decode, TypeInfo)]
116pub enum RewardAccount {
117    /// Pay rewards to the sender's account and increase the amount at stake.
118    Staked,
119    /// Pay rewards to the sender's account (usually, the one derived from `program_id`)
120    /// without increasing the amount at stake.
121    Program,
122    /// Pay rewards to a custom account.
123    Custom(ActorId),
124    /// Opt for not receiving any rewards at all.
125    None,
126}
127
128/// Response type for staking built-in actor operations.
129#[derive(Debug, Clone, Eq, PartialEq, Encode, Decode, TypeInfo)]
130pub enum Response {
131    /// Response containing the active era details and when it was executed.
132    ActiveEra {
133        /// Information about the active era.
134        info: ActiveEraInfo,
135        /// Block number when the request was executed.
136        executed_at: u32,
137        /// Gear block number when the request was executed.
138        executed_at_gear_block: u32,
139    },
140}
141
142/// Information about the active era.
143#[derive(Debug, Clone, Eq, PartialEq, Encode, Decode, TypeInfo)]
144pub struct ActiveEraInfo {
145    /// Current active era index.
146    pub index: u32,
147    /// Moment of start expressed as millisecond from `$UNIX_EPOCH`.
148    ///
149    /// Start can be none if start hasn't been set for the era yet.
150    /// Start is set on the first `on_finalize` of the era to guarantee usage of `Time`.
151    pub start: Option<u64>,
152}
gbuiltin_staking/lib.rs

gbuiltin_staking/
lib.rs
