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
57#![no_std]
58
59extern crate alloc;
60
61use alloc::vec::Vec;
62use gprimitives::ActorId;
63use parity_scale_codec::{Decode, Encode};
64use scale_info::TypeInfo;
65
66/// Type that should be used to create a message to the staking built-in actor.
67///
68/// A `partial` mirror of the staking pallet interface. Not all extrinsics
69/// are supported, more can be added as needed for real-world use cases.
70#[derive(Debug, Clone, Eq, PartialEq, Encode, Decode, TypeInfo)]
71pub enum Request {
72    /// Bond up to the `value` from the sender to self as the controller.
73    #[codec(index = 0)]
74    Bond { value: u128, payee: RewardAccount },
75
76    /// Add up to the `value` to the sender's bonded amount.
77    #[codec(index = 1)]
78    BondExtra { value: u128 },
79
80    /// Unbond up to the `value` to allow withdrawal after undonding period.
81    #[codec(index = 2)]
82    Unbond { value: u128 },
83
84    /// Withdraw unbonded chunks for which undonding period has elapsed.
85    #[codec(index = 3)]
86    WithdrawUnbonded { num_slashing_spans: u32 },
87
88    /// Add sender as a nominator of `targets` or update the existing targets.
89    #[codec(index = 4)]
90    Nominate { targets: Vec<ActorId> },
91
92    /// Declare intention to `temporarily` stop nominating while still having funds bonded.
93    #[codec(index = 5)]
94    Chill,
95
96    /// Request stakers payout for the given era.
97    #[codec(index = 6)]
98    PayoutStakers { validator_stash: ActorId, era: u32 },
99
100    /// Rebond a portion of the sender's stash scheduled to be unlocked.
101    #[codec(index = 7)]
102    Rebond { value: u128 },
103
104    /// Set the reward destination.
105    #[codec(index = 8)]
106    SetPayee { payee: RewardAccount },
107}
108
109/// An account where the rewards should accumulate on.
110///
111/// A "mirror" of the staking pallet's `RewardDestination` enum.
112#[derive(Debug, Clone, Copy, Eq, PartialEq, Encode, Decode, TypeInfo)]
113pub enum RewardAccount {
114    /// Pay rewards to the sender's account and increase the amount at stake.
115    Staked,
116    /// Pay rewards to the sender's account (usually, the one derived from `program_id`)
117    /// without increasing the amount at stake.
118    Program,
119    /// Pay rewards to a custom account.
120    Custom(ActorId),
121    /// Opt for not receiving any rewards at all.
122    None,
123}
gbuiltin_staking/lib.rs

gbuiltin_staking/
lib.rs
