cbe_program/lib.rs
1//! The base library for all Cartallum CBE on-chain Rust programs.
2//!
3//! All Cartallum CBE Rust programs that run on-chain will link to this crate, which
4//! acts as a standard library for Cartallum CBE programs. Cartallum CBE programs also link to
5//! the [Rust standard library][std], though it is [modified][sstd] for the
6//! Cartallum CBE runtime environment. While off-chain programs that interact with the
7//! Cartallum CBE network _can_ link to this crate, they typically instead use the
8//! [`cbe-sdk`] crate, which reexports all modules from `cbe-program`.
9//!
10//! [std]: https://doc.rust-lang.org/stable/std/
11//! [sstd]: https://docs.cartallum.com/developing/on-chain-programs/developing-rust#restrictions
12//! [`cbe-sdk`]: https://docs.cartallum.com/cbe-sdk/latest/cbe_sdk/
13//!
14//! This library defines
15//!
16//! - macros for declaring the [program entrypoint][pe],
17//! - [core data types][cdt],
18//! - [logging] macros,
19//! - [serialization] methods,
20//! - methods for [cross-program instruction execution][cpi],
21//! - program IDs and instruction constructors for the system program and other
22//! [native programs][np],
23//! - [sysvar] accessors.
24//!
25//! [pe]: #defining-a-cbe-program
26//! [cdt]: #core-data-types
27//! [logging]: crate::log
28//! [serialization]: #serialization
29//! [np]: #native-programs
30//! [cpi]: #cross-program-instruction-execution
31//! [sysvar]: crate::sysvar
32//!
33//! Idiomatic examples of `cbe-program` usage can be found in
34//! [the Cartallum CBE Program Library][spl].
35//!
36//! [spl]: https://github.com/Cartallum/cbe-program-library
37//!
38//! # Defining a cbe program
39//!
40//! Cartallum CBE program crates have some unique properties compared to typical Rust
41//! programs:
42//!
43//! - They are often compiled for both on-chain use and off-chain use. This is
44//! primarily because off-chain clients may need access to data types
45//! defined by the on-chain program.
46//! - They do not define a `main` function, but instead define their entrypoint
47//! with the [`entrypoint!`] macro.
48//! - They are compiled as the ["cdylib"] crate type for dynamic loading
49//! by the Cartallum CBE runtime.
50//! - They run in a constrained VM environment, and while they do have access to
51//! the [Rust standard library][std], many features of the standard library,
52//! particularly related to OS services, will fail at runtime, will silently
53//! do nothing, or are not defined. See the [restrictions to the Rust standard
54//! library][sstd] in the Cartallum CBE documentation for more.
55//!
56//! [std]: https://doc.rust-lang.org/std/index.html
57//! ["cdylib"]: https://doc.rust-lang.org/reference/linkage.html
58//!
59//! Because multiple crates that are linked together cannot all define
60//! program entrypoints (see the [`entrypoint!`] documentation) a common
61//! convention is to use a [Cargo feature] called `no-entrypoint` to allow
62//! the program entrypoint to be disabled.
63//!
64//! [Cargo feature]: https://doc.rust-lang.org/cargo/reference/features.html
65//!
66//! The skeleton of a Cartallum CBE program typically looks like:
67//!
68//! ```
69//! #[cfg(not(feature = "no-entrypoint"))]
70//! pub mod entrypoint {
71//! use cbe_program::{
72//! account_info::AccountInfo,
73//! entrypoint,
74//! entrypoint::ProgramResult,
75//! pubkey::Pubkey,
76//! };
77//!
78//! entrypoint!(process_instruction);
79//!
80//! pub fn process_instruction(
81//! program_id: &Pubkey,
82//! accounts: &[AccountInfo],
83//! instruction_data: &[u8],
84//! ) -> ProgramResult {
85//! // Decode and dispatch instructions here.
86//! todo!()
87//! }
88//! }
89//!
90//! // Additional code goes here.
91//! ```
92//!
93//! With a `Cargo.toml` file that contains
94//!
95//! ```toml
96//! [lib]
97//! crate-type = ["cdylib", "rlib"]
98//!
99//! [features]
100//! no-entrypoint = []
101//! ```
102//!
103//! Note that a Cartallum CBE program must specify its crate-type as "cdylib", and
104//! "cdylib" crates will automatically be discovered and built by the `cargo
105//! build-bpf` command. Cartallum CBE programs also often have crate-type "rlib" so
106//! they can be linked to other Rust crates.
107//!
108//! # On-chain vs. off-chain compilation targets
109//!
110//! Cartallum CBE programs run on the [rbpf] VM, which implements a variant of the
111//! [eBPF] instruction set. Because this crate can be compiled for both on-chain
112//! and off-chain execution, the environments of which are significantly
113//! different, it extensively uses [conditional compilation][cc] to tailor its
114//! implementation to the environment. The `cfg` predicate used for identifying
115//! compilation for on-chain programs is `target_os = "cbe"`, as in this
116//! example from the `cbe-program` codebase that logs a message via a
117//! syscall when run on-chain, and via a library call when offchain:
118//!
119//! [rbpf]: https://github.com/Cartallum/rbpf
120//! [eBPF]: https://ebpf.io/
121//! [cc]: https://doc.rust-lang.org/reference/conditional-compilation.html
122//!
123//! ```
124//! pub fn cbe_log(message: &str) {
125//! #[cfg(target_os = "cbe")]
126//! unsafe {
127//! cbe_log_(message.as_ptr(), message.len() as u64);
128//! }
129//!
130//! #[cfg(not(target_os = "cbe"))]
131//! program_stubs::cbe_log(message);
132//! }
133//! # mod program_stubs {
134//! # pub(crate) fn cbe_log(message: &str) { }
135//! # }
136//! ```
137//!
138//! This `cfg` pattern is suitable as well for user code that needs to work both
139//! on-chain and off-chain.
140//!
141//! `cbe-program` and `cbe-sdk` were previously a single crate. Because of
142//! this history, and because of the dual-usage of `cbe-program` for two
143//! different environments, it contains some features that are not available to
144//! on-chain programs at compile-time. It also contains some on-chain features
145//! that will fail in off-chain scenarios at runtime. This distinction is not
146//! well-reflected in the documentation.
147//!
148//! For a more complete description of Cartallum CBE's implementation of eBPF and its
149//! limitations, see the main Cartallum CBE documentation for [on-chain programs][ocp].
150//!
151//! [ocp]: https://docs.cartallum.com/developing/on-chain-programs/overview
152//!
153//! # Core data types
154//!
155//! - [`Pubkey`] — The address of a [Cartallum CBE account][acc]. Some account
156//! addresses are [ed25519] public keys, with corresponding secret keys that
157//! are managed off-chain. Often, though, account addresses do not have
158//! corresponding secret keys — as with [_program derived
159//! addresses_][pdas] — or the secret key is not relevant to the
160//! operation of a program, and may have even been disposed of. As running
161//! Cartallum CBE programs can not safely create or manage secret keys, the full
162//! [`Keypair`] is not defined in `cbe-program` but in `cbe-sdk`.
163//! - [`Hash`] — A cryptographic hash. Used to uniquely identify blocks,
164//! and also for general purpose hashing.
165//! - [`AccountInfo`] — A description of a single Cartallum CBE account. All accounts
166//! that might be accessed by a program invocation are provided to the program
167//! entrypoint as `AccountInfo`.
168//! - [`Instruction`] — A directive telling the runtime to execute a program,
169//! passing it a set of accounts and program-specific data.
170//! - [`ProgramError`] and [`ProgramResult`] — The error type that all programs
171//! must return, reported to the runtime as a `u64`.
172//! - [`CBC`] — The Cartallum CBE native token type, with conversions to and from
173//! [_scoobies_], the smallest fractional unit of CBC, in the [`native_token`]
174//! module.
175//!
176//! [acc]: https://docs.cartallum.com/developing/programming-model/accounts
177//! [`Pubkey`]: pubkey::Pubkey
178//! [`Hash`]: hash::Hash
179//! [`Instruction`]: instruction::Instruction
180//! [`AccountInfo`]: account_info::AccountInfo
181//! [`ProgramError`]: program_error::ProgramError
182//! [`ProgramResult`]: entrypoint::ProgramResult
183//! [ed25519]: https://ed25519.cr.yp.to/
184//! [`Keypair`]: https://docs.cartallum.com/cbe-sdk/latest/cbe_sdk/signer/keypair/struct.Keypair.html
185//! [SHA-256]: https://en.wikipedia.org/wiki/SHA-2
186//! [`CBC`]: native_token::CBC
187//! [_scoobies_]: https://docs.cartallum.com/introduction#what-are-cbcs
188//!
189//! # Serialization
190//!
191//! Within the Cartallum CBE runtime, programs, and network, at least three different
192//! serialization formats are used, and `cbe-program` provides access to
193//! those needed by programs.
194//!
195//! In user-written Cartallum CBE program code, serialization is primarily used for
196//! accessing [`AccountInfo`] data and [`Instruction`] data, both of which are
197//! program-specific binary data. Every program is free to decide their own
198//! serialization format, but data received from other sources —
199//! [sysvars][sysvar] for example — must be deserialized using the methods
200//! indicated by the documentation for that data or data type.
201//!
202//! [`AccountInfo`]: account_info::AccountInfo
203//! [`Instruction`]: instruction::Instruction
204//!
205//! The three serialization formats in use in Cartallum CBE are:
206//!
207//! - __[Borsh]__, a compact and well-specified format developed by the [NEAR]
208//! project, suitable for use in protocol definitions and for archival storage.
209//! It has a [Rust implementation][brust] and a [JavaScript implementation][bjs]
210//! and is recommended for all purposes.
211//!
212//! Users need to import the [`borsh`] crate themselves — it is not
213//! re-exported by `cbe-program`, though this crate provides several useful
214//! utilities in its [`borsh` module][borshmod] that are not available in the
215//! `borsh` library.
216//!
217//! The [`Instruction::new_with_borsh`] function creates an `Instruction` by
218//! serializing a value with borsh.
219//!
220//! [Borsh]: https://borsh.io/
221//! [NEAR]: https://near.org/
222//! [brust]: https://docs.cartallum.com/borsh
223//! [bjs]: https://github.com/near/borsh-js
224//! [`borsh`]: https://docs.cartallum.com/borsh
225//! [borshmod]: crate::borsh
226//! [`Instruction::new_with_borsh`]: instruction::Instruction::new_with_borsh
227//!
228//! - __[Bincode]__, a compact serialization format that implements the [Serde]
229//! Rust APIs. As it does not have a specification nor a JavaScript
230//! implementation, and uses more CPU than borsh, it is not recommend for new
231//! code.
232//!
233//! Many system program and native program instructions are serialized with
234//! bincode, and it is used for other purposes in the runtime. In these cases
235//! Rust programmers are generally not directly exposed to the encoding format
236//! as it is hidden behind APIs.
237//!
238//! The [`Instruction::new_with_bincode`] function creates an `Instruction` by
239//! serializing a value with bincode.
240//!
241//! [Bincode]: https://docs.cartallum.com/bincode
242//! [Serde]: https://serde.rs/
243//! [`Instruction::new_with_bincode`]: instruction::Instruction::new_with_bincode
244//!
245//! - __[`Pack`]__, a Cartallum CBE-specific serialization API that is used by many
246//! older programs in the [Cartallum CBE Program Library][spl] to define their
247//! account format. It is difficult to implement and does not define a
248//! language-independent serialization format. It is not generally recommended
249//! for new code.
250//!
251//! [`Pack`]: program_pack::Pack
252//!
253//! Developers should carefully consider the CPU cost of serialization, balanced
254//! against the need for correctness and ease of use: off-the-shelf
255//! serialization formats tend to be more expensive than carefully hand-written
256//! application-specific formats; but application-specific formats are more
257//! difficult to ensure the correctness of, and to provide multi-language
258//! implementations for. It is not uncommon for programs to pack and unpack
259//! their data with hand-written code.
260//!
261//! # Cross-program instruction execution
262//!
263//! Cartallum CBE programs may call other programs, termed [_cross-program
264//! invocation_][cpi] (CPI), with the [`invoke`] and [`invoke_signed`]
265//! functions. When calling another program the caller must provide the
266//! [`Instruction`] to be invoked, as well as the [`AccountInfo`] for every
267//! account required by the instruction. Because the only way for a program to
268//! acquire `AccountInfo` values is by receiving them from the runtime at the
269//! [program entrypoint][entrypoint!], any account required by the callee
270//! program must transitively be required by the caller program, and provided by
271//! _its_ caller.
272//!
273//! [`invoke`]: program::invoke
274//! [`invoke_signed`]: program::invoke_signed
275//! [cpi]: https://docs.cartallum.com/developing/programming-model/calling-between-programs
276//!
277//! A simple example of transferring scoobies via CPI:
278//!
279//! ```
280//! use cbe_program::{
281//! account_info::{next_account_info, AccountInfo},
282//! entrypoint,
283//! entrypoint::ProgramResult,
284//! program::invoke,
285//! pubkey::Pubkey,
286//! system_instruction,
287//! system_program,
288//! };
289//!
290//! entrypoint!(process_instruction);
291//!
292//! fn process_instruction(
293//! program_id: &Pubkey,
294//! accounts: &[AccountInfo],
295//! instruction_data: &[u8],
296//! ) -> ProgramResult {
297//! let account_info_iter = &mut accounts.iter();
298//!
299//! let payer = next_account_info(account_info_iter)?;
300//! let recipient = next_account_info(account_info_iter)?;
301//! // The system program is a required account to invoke a system
302//! // instruction, even though we don't use it directly.
303//! let system_account = next_account_info(account_info_iter)?;
304//!
305//! assert!(payer.is_writable);
306//! assert!(payer.is_signer);
307//! assert!(recipient.is_writable);
308//! assert!(system_program::check_id(system_account.key));
309//!
310//! let scoobies = 1000000;
311//!
312//! invoke(
313//! &system_instruction::transfer(payer.key, recipient.key, scoobies),
314//! &[payer.clone(), recipient.clone(), system_account.clone()],
315//! )
316//! }
317//! ```
318//!
319//! Cartallum CBE also includes a mechanism to let programs control and sign for
320//! accounts without needing to protect a corresponding secret key, called
321//! [_program derived addresses_][pdas]. PDAs are derived with the
322//! [`Pubkey::find_program_address`] function. With a PDA, a program can call
323//! `invoke_signed` to call another program while virtually "signing" for the
324//! PDA.
325//!
326//! [pdas]: https://docs.cartallum.com/developing/programming-model/calling-between-programs#program-derived-addresses
327//! [`Pubkey::find_program_address`]: pubkey::Pubkey::find_program_address
328//!
329//! A simple example of creating an account for a PDA:
330//!
331//! ```
332//! use cbe_program::{
333//! account_info::{next_account_info, AccountInfo},
334//! entrypoint,
335//! entrypoint::ProgramResult,
336//! program::invoke_signed,
337//! pubkey::Pubkey,
338//! system_instruction,
339//! system_program,
340//! };
341//!
342//! entrypoint!(process_instruction);
343//!
344//! fn process_instruction(
345//! program_id: &Pubkey,
346//! accounts: &[AccountInfo],
347//! instruction_data: &[u8],
348//! ) -> ProgramResult {
349//! let account_info_iter = &mut accounts.iter();
350//! let payer = next_account_info(account_info_iter)?;
351//! let vault_pda = next_account_info(account_info_iter)?;
352//! let system_program = next_account_info(account_info_iter)?;
353//!
354//! assert!(payer.is_writable);
355//! assert!(payer.is_signer);
356//! assert!(vault_pda.is_writable);
357//! assert_eq!(vault_pda.owner, &system_program::ID);
358//! assert!(system_program::check_id(system_program.key));
359//!
360//! let vault_bump_seed = instruction_data[0];
361//! let vault_seeds = &[b"vault", payer.key.as_ref(), &[vault_bump_seed]];
362//! let expected_vault_pda = Pubkey::create_program_address(vault_seeds, program_id)?;
363//!
364//! assert_eq!(vault_pda.key, &expected_vault_pda);
365//!
366//! let scoobies = 10000000;
367//! let vault_size = 16;
368//!
369//! invoke_signed(
370//! &system_instruction::create_account(
371//! &payer.key,
372//! &vault_pda.key,
373//! scoobies,
374//! vault_size,
375//! &program_id,
376//! ),
377//! &[
378//! payer.clone(),
379//! vault_pda.clone(),
380//! ],
381//! &[
382//! &[
383//! b"vault",
384//! payer.key.as_ref(),
385//! &[vault_bump_seed],
386//! ],
387//! ]
388//! )?;
389//! Ok(())
390//! }
391//! ```
392//!
393//! # Native programs
394//!
395//! Some Cartallum CBE programs are [_native programs_][np2], running native machine
396//! code that is distributed with the runtime, with well-known program IDs.
397//!
398//! [np2]: https://docs.cartallum.com/developing/runtime-facilities/programs
399//!
400//! Some native programs can be [invoked][cpi] by other programs, but some can
401//! only be executed as "top-level" instructions included by off-chain clients
402//! in a [`Transaction`].
403//!
404//! [`Transaction`]: https://docs.cartallum.com/cbe-sdk/latest/cbe_sdk/transaction/struct.Transaction.html
405//!
406//! This crate defines the program IDs for most native programs. Even though
407//! some native programs cannot be invoked by other programs, a Cartallum CBE program
408//! may need access to their program IDs. For example, a program may need to
409//! verify that an ed25519 signature verification instruction was included in
410//! the same transaction as its own instruction. For many native programs, this
411//! crate also defines enums that represent the instructions they process, and
412//! constructors for building the instructions.
413//!
414//! Locations of program IDs and instruction constructors are noted in the list
415//! below, as well as whether they are invokable by other programs.
416//!
417//! While some native programs have been active since the genesis block, others
418//! are activated dynamically after a specific [slot], and some are not yet
419//! active. This documentation does not distinguish which native programs are
420//! active on any particular network. The `cbe feature status` CLI command
421//! can help in determining active features.
422//!
423//! [slot]: https://docs.cartallum.com/terminology#slot
424//!
425//! Native programs important to Cartallum CBE program authors include:
426//!
427//! - __System Program__: Creates new accounts, allocates account data, assigns
428//! accounts to owning programs, transfers scoobies from System Program owned
429//! accounts and pays transaction fees.
430//! - ID: [`cbe_program::system_program`]
431//! - Instruction: [`cbe_program::system_instruction`]
432//! - Invokable by programs? yes
433//!
434//! - __Compute Budget Program__: Requests additional CPU or memory resources
435//! for a transaction. This program does nothing when called from another
436//! program.
437//! - ID: [`cbe_sdk::compute_budget`](https://docs.cartallum.com/cbe-sdk/latest/cbe_sdk/compute_budget/index.html)
438//! - Instruction: [`cbe_sdk::compute_budget`](https://docs.cartallum.com/cbe-sdk/latest/cbe_sdk/compute_budget/index.html)
439//! - Invokable by programs? no
440//!
441//! - __ed25519 Program__: Verifies an ed25519 signature.
442//! - ID: [`cbe_program::ed25519_program`]
443//! - Instruction: [`cbe_sdk::ed25519_instruction`](https://docs.cartallum.com/cbe-sdk/latest/cbe_sdk/ed25519_instruction/index.html)
444//! - Invokable by programs? no
445//!
446//! - __secp256k1 Program__: Verifies secp256k1 public key recovery operations.
447//! - ID: [`cbe_program::secp256k1_program`]
448//! - Instruction: [`cbe_sdk::secp256k1_instruction`](https://docs.cartallum.com/cbe-sdk/latest/cbe_sdk/secp256k1_instruction/index.html)
449//! - Invokable by programs? no
450//!
451//! - __BPF Loader__: Deploys, and executes immutable programs on the chain.
452//! - ID: [`cbe_program::bpf_loader`]
453//! - Instruction: [`cbe_program::loader_instruction`]
454//! - Invokable by programs? yes
455//!
456//! - __Upgradable BPF Loader__: Deploys, upgrades, and executes upgradable
457//! programs on the chain.
458//! - ID: [`cbe_program::bpf_loader_upgradeable`]
459//! - Instruction: [`cbe_program::loader_upgradeable_instruction`]
460//! - Invokable by programs? yes
461//!
462//! - __Deprecated BPF Loader__: Deploys, and executes immutable programs on the
463//! chain.
464//! - ID: [`cbe_program::bpf_loader_deprecated`]
465//! - Instruction: [`cbe_program::loader_instruction`]
466//! - Invokable by programs? yes
467//!
468//! [lut]: https://docs.cartallum.com/proposals/versioned-transactions
469
470#![allow(incomplete_features)]
471#![cfg_attr(RUSTC_WITH_SPECIALIZATION, feature(specialization))]
472#![cfg_attr(RUSTC_NEEDS_PROC_MACRO_HYGIENE, feature(proc_macro_hygiene))]
473
474// Allows macro expansion of `use ::cbe_program::*` to work within this crate
475extern crate self as cbe_program;
476
477pub mod account_info;
478pub mod address_lookup_table_account;
479pub mod alt_bn128;
480pub(crate) mod atomic_u64;
481pub mod blake3;
482pub mod borsh;
483pub mod bpf_loader;
484pub mod bpf_loader_deprecated;
485pub mod bpf_loader_upgradeable;
486pub mod clock;
487pub mod debug_account_data;
488pub mod decode_error;
489pub mod ed25519_program;
490pub mod entrypoint;
491pub mod entrypoint_deprecated;
492pub mod epoch_schedule;
493pub mod feature;
494pub mod fee_calculator;
495pub mod hash;
496pub mod incinerator;
497pub mod instruction;
498pub mod keccak;
499pub mod scoobies;
500pub mod loader_instruction;
501pub mod loader_upgradeable_instruction;
502pub mod log;
503pub mod message;
504pub mod native_token;
505pub mod nonce;
506pub mod program;
507pub mod program_error;
508pub mod program_memory;
509pub mod program_option;
510pub mod program_pack;
511pub mod program_stubs;
512pub mod program_utils;
513pub mod pubkey;
514pub mod rent;
515pub mod sanitize;
516pub mod secp256k1_program;
517pub mod secp256k1_recover;
518pub mod serde_varint;
519pub mod serialize_utils;
520pub mod short_vec;
521pub mod slot_hashes;
522pub mod slot_history;
523pub mod stake;
524pub mod stake_history;
525pub mod syscalls;
526pub mod system_instruction;
527pub mod system_program;
528pub mod sysvar;
529pub mod vote;
530pub mod wasm;
531
532#[cfg(target_os = "cbe")]
533pub use cbe_sdk_macro::wasm_bindgen_stub as wasm_bindgen;
534/// Re-export of [wasm-bindgen].
535///
536/// [wasm-bindgen]: https://rustwasm.github.io/docs/wasm-bindgen/
537#[cfg(not(target_os = "cbe"))]
538pub use wasm_bindgen::prelude::wasm_bindgen;
539
540/// The [config native program][np].
541///
542/// [np]: https://docs.cartallum.com/developing/runtime-facilities/programs#config-program
543pub mod config {
544 pub mod program {
545 crate::declare_id!("Config1111111111111111111111111111111111111");
546 }
547}
548
549/// A vector of Cartallum CBE SDK IDs.
550pub mod sdk_ids {
551 use {
552 crate::{
553 bpf_loader, bpf_loader_deprecated, bpf_loader_upgradeable, config, ed25519_program,
554 feature, incinerator, secp256k1_program, cbe_program::pubkey::Pubkey, stake,
555 system_program, sysvar, vote,
556 },
557 lazy_static::lazy_static,
558 };
559
560 lazy_static! {
561 pub static ref SDK_IDS: Vec<Pubkey> = {
562 let mut sdk_ids = vec![
563 ed25519_program::id(),
564 secp256k1_program::id(),
565 system_program::id(),
566 sysvar::id(),
567 bpf_loader::id(),
568 bpf_loader_upgradeable::id(),
569 incinerator::id(),
570 config::program::id(),
571 vote::program::id(),
572 feature::id(),
573 bpf_loader_deprecated::id(),
574 stake::config::id(),
575 ];
576 sdk_ids.extend(sysvar::ALL_IDS.iter());
577 sdk_ids
578 };
579 }
580}
581
582/// Same as [`declare_id`] except that it reports that this ID has been deprecated.
583pub use cbe_sdk_macro::program_declare_deprecated_id as declare_deprecated_id;
584/// Convenience macro to declare a static public key and functions to interact with it.
585///
586/// Input: a single literal base58 string representation of a program's ID.
587///
588/// # Example
589///
590/// ```
591/// # // wrapper is used so that the macro invocation occurs in the item position
592/// # // rather than in the statement position which isn't allowed.
593/// use std::str::FromStr;
594/// use cbe_program::{declare_id, pubkey::Pubkey};
595///
596/// # mod item_wrapper {
597/// # use cbe_program::declare_id;
598/// declare_id!("My11111111111111111111111111111111111111111");
599/// # }
600/// # use item_wrapper::id;
601///
602/// let my_id = Pubkey::from_str("My11111111111111111111111111111111111111111").unwrap();
603/// assert_eq!(id(), my_id);
604/// ```
605pub use cbe_sdk_macro::program_declare_id as declare_id;
606/// Convenience macro to define a static public key.
607///
608/// Input: a single literal base58 string representation of a Pubkey.
609///
610/// # Example
611///
612/// ```
613/// use std::str::FromStr;
614/// use cbe_program::{pubkey, pubkey::Pubkey};
615///
616/// static ID: Pubkey = pubkey!("My11111111111111111111111111111111111111111");
617///
618/// let my_id = Pubkey::from_str("My11111111111111111111111111111111111111111").unwrap();
619/// assert_eq!(ID, my_id);
620/// ```
621pub use cbe_sdk_macro::program_pubkey as pubkey;
622
623#[macro_use]
624extern crate serde_derive;
625
626#[macro_use]
627extern crate cbe_frozen_abi_macro;
628
629/// Convenience macro for doing integer division where the operation's safety
630/// can be checked at compile-time.
631///
632/// Since `unchecked_div_by_const!()` is supposed to fail at compile-time, abuse
633/// doctests to cover failure modes
634///
635/// # Examples
636///
637/// Literal denominator div-by-zero fails:
638///
639/// ```compile_fail
640/// # use cbe_program::unchecked_div_by_const;
641/// # fn main() {
642/// let _ = unchecked_div_by_const!(10, 0);
643/// # }
644/// ```
645///
646/// Const denominator div-by-zero fails:
647///
648/// ```compile_fail
649/// # use cbe_program::unchecked_div_by_const;
650/// # fn main() {
651/// const D: u64 = 0;
652/// let _ = unchecked_div_by_const!(10, D);
653/// # }
654/// ```
655///
656/// Non-const denominator fails:
657///
658/// ```compile_fail
659/// # use cbe_program::unchecked_div_by_const;
660/// # fn main() {
661/// let d = 0;
662/// let _ = unchecked_div_by_const!(10, d);
663/// # }
664/// ```
665///
666/// Literal denominator div-by-zero fails:
667///
668/// ```compile_fail
669/// # use cbe_program::unchecked_div_by_const;
670/// # fn main() {
671/// const N: u64 = 10;
672/// let _ = unchecked_div_by_const!(N, 0);
673/// # }
674/// ```
675///
676/// Const denominator div-by-zero fails:
677///
678/// ```compile_fail
679/// # use cbe_program::unchecked_div_by_const;
680/// # fn main() {
681/// const N: u64 = 10;
682/// const D: u64 = 0;
683/// let _ = unchecked_div_by_const!(N, D);
684/// # }
685/// ```
686///
687/// Non-const denominator fails:
688///
689/// ```compile_fail
690/// # use cbe_program::unchecked_div_by_const;
691/// # fn main() {
692/// # const N: u64 = 10;
693/// let d = 0;
694/// let _ = unchecked_div_by_const!(N, d);
695/// # }
696/// ```
697///
698/// Literal denominator div-by-zero fails:
699///
700/// ```compile_fail
701/// # use cbe_program::unchecked_div_by_const;
702/// # fn main() {
703/// let n = 10;
704/// let _ = unchecked_div_by_const!(n, 0);
705/// # }
706/// ```
707///
708/// Const denominator div-by-zero fails:
709///
710/// ```compile_fail
711/// # use cbe_program::unchecked_div_by_const;
712/// # fn main() {
713/// let n = 10;
714/// const D: u64 = 0;
715/// let _ = unchecked_div_by_const!(n, D);
716/// # }
717/// ```
718///
719/// Non-const denominator fails:
720///
721/// ```compile_fail
722/// # use cbe_program::unchecked_div_by_const;
723/// # fn main() {
724/// let n = 10;
725/// let d = 0;
726/// let _ = unchecked_div_by_const!(n, d);
727/// # }
728/// ```
729#[macro_export]
730macro_rules! unchecked_div_by_const {
731 ($num:expr, $den:expr) => {{
732 // Ensure the denominator is compile-time constant
733 let _ = [(); ($den - $den) as usize];
734 // Compile-time constant integer div-by-zero passes for some reason
735 // when invoked from a compilation unit other than that where this
736 // macro is defined. Do an explicit zero-check for now. Sorry about the
737 // ugly error messages!
738 // https://users.rust-lang.org/t/unexpected-behavior-of-compile-time-integer-div-by-zero-check-in-declarative-macro/56718
739 let _ = [(); ($den as usize) - 1];
740 #[allow(clippy::integer_arithmetic)]
741 let quotient = $num / $den;
742 quotient
743 }};
744}
745
746// This module is purposefully listed after all other exports: because of an
747// interaction within rustdoc between the reexports inside this module of
748// `cbe_program`'s top-level modules, and `cbe_sdk`'s glob re-export of
749// `cbe_program`'s top-level modules, if this module is not lexically last
750// rustdoc fails to generate documentation for the re-exports within
751// `cbe_sdk`.
752#[cfg(not(target_os = "cbe"))]
753pub mod example_mocks;
754
755#[cfg(test)]
756mod tests {
757 use super::unchecked_div_by_const;
758
759 #[test]
760 fn test_unchecked_div_by_const() {
761 const D: u64 = 2;
762 const N: u64 = 10;
763 let n = 10;
764 assert_eq!(unchecked_div_by_const!(10, 2), 5);
765 assert_eq!(unchecked_div_by_const!(N, 2), 5);
766 assert_eq!(unchecked_div_by_const!(n, 2), 5);
767 assert_eq!(unchecked_div_by_const!(10, D), 5);
768 assert_eq!(unchecked_div_by_const!(N, D), 5);
769 assert_eq!(unchecked_div_by_const!(n, D), 5);
770 }
771}