feat: Candid export (internet-computer-protocol#3)

* feat: export candid

Signed-off-by: benjizhai <[email protected]>

* feat: export candid

Signed-off-by: benjizhai <[email protected]>

* feat: export candid

Signed-off-by: benjizhai <[email protected]>

* feat: export candid

Signed-off-by: benjizhai <[email protected]>

* feat: export candid

Signed-off-by: benjizhai <[email protected]>

* feat: export candid

Signed-off-by: benjizhai <[email protected]>

---------

Signed-off-by: benjizhai <[email protected]>

Author: benjizhai

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "rustic"
-version = "0.1.5"
+version = "0.1.6"
 authors = ["Benji Zhai"]
 edition = "2021"
 rust-version = "1.65.0"
@@ -18,8 +18,8 @@ categories = ["cryptography::cryptocurrencies", "finance", "wasm"]
 [dependencies]
 candid = { version = "0.9", features = ["parser"] }
 ciborium = "0.2"
-ic-cdk = "0.10"
-ic-cdk-macros = "0.7"
+ic-cdk = "0.11"
+ic-cdk-macros = "0.8"
 ic-stable-structures = "0.5"
 num-traits = "0.2"
 serde = "1.0"
@@ -30,6 +30,7 @@ rustic-macros = "0.1"
 default = ["access-roles", "reentrancy", "lifecycle"]
 access = []
 access-roles = ["access"]
+export-candid = []
 lifecycle = []
 logging = []
 pausable = ["access"]

Cargo.toml

@@ -56,6 +56,15 @@ pub fn post_upgrade () {
 }
 ```
 
+## Export Candid
+The `export-candid` allows candid export using the mechanism introduced in `ic-cdk` [v0.11](https://github.com/dfinity/cdk-rs/blob/main/src/ic-cdk/CHANGELOG.md#0110---2023-09-18). However due to how this mechanism works, the candid needs to be exported twice, once in your application and once from the Rustic library.
+
+To export the candid from Rustic, use Rustic with the `export-candid` feature, and comment out `ic_cdk::export_candid!()` in your main canister to avoid conflicts. Then generate wasm once, and use [`candid-extractor`](https://github.com/dfinity/cdk-rs/tree/main/src/candid-extractor) to extract the candid.
+
+Then to export candid from your main application, disable the `export-candid` feature, add `ic_cdk::export_candid!()` to your main canister, compile and extract candid again.
+
+Manually combine the two candid files to get the final candid for your canister.
+
 ## Lifecycle
 When using the `lifecycle` feature (enabled by default), in the post-upgrade hook of the new canister, the `lifecycle_on_upgrade` method is called via calling `rustic::rustic_post_upgrade`. For the semver you'll need to specify whether you want a major/minor/patchlevel version bump. If the stable memory layout changed (make sure you test compatibility as this is not checked by rustic), bump the stable memory version. If you bump the major version then the minor/patchlevel are ignored and will be set to start from 0. 
 

README.md

@@ -33,7 +33,7 @@ use crate::memory_map::*;
 use crate::testing::*;
 use crate::types::*;
 use crate::utils::*;
-use candid::{candid_method, CandidType, Principal};
+use candid::{CandidType, Principal};
 use ic_cdk_macros::{query, update};
 use ic_stable_structures::{DefaultMemoryImpl, StableBTreeMap, StableCell};
 use rustic_macros::modifiers;
@@ -104,7 +104,6 @@ pub fn only_owner() -> Result<(), String> {
 }
 
 /// Checks if a principal is the owner.
-#[candid_method(query)]
 #[query]
 pub fn is_owner(owner: Principal) -> bool {
     ACCESS_CONTROL.with(|c| {
@@ -120,7 +119,6 @@ pub fn is_owner(owner: Principal) -> bool {
 /// The ownership is not affected until the new owners calls [`accept_ownership`],
 /// at which point ownership would be transfered from the original owner to the new owner.
 /// If the `new_owner` is set to `None`, then any pending ownership transfer is cancelled.
-#[candid_method(update)]
 #[update]
 #[modifiers("only_owner")]
 pub fn transfer_ownership(new_owner: Option<Principal>) {
@@ -147,7 +145,6 @@ pub fn transfer_ownership(new_owner: Option<Principal>) {
 ///
 /// The use of this function is discouraged, as there is no recourse if the wrong principal is specified.
 /// This function is useful in cases where the accepting principal cannot call [`accept_ownership`].
-#[candid_method(update)]
 #[update]
 #[modifiers("only_owner")]
 pub fn transfer_ownership_immediate(new_owner: Option<Principal>) {
@@ -171,7 +168,6 @@ pub fn transfer_ownership_immediate(new_owner: Option<Principal>) {
 }
 
 /// Accepts ownership transfer. The caller must be the pending owner.
-#[candid_method(update)]
 #[update]
 pub fn accept_ownership() {
     ACCESS_CONTROL.with(|c| {
@@ -194,15 +190,13 @@ pub fn accept_ownership() {
 }
 
 /// Query method to get the current owner.
-#[candid_method(query)]
 #[query]
 pub fn owner() -> Option<Principal> {
     #[allow(clippy::unwrap_used)] // unwrap desired
     ACCESS_CONTROL.with(|c| c.borrow().get().0.clone().unwrap().owner)
 }
 
 /// Query method to get the current pending owner.
-#[candid_method(query)]
 #[query]
 pub fn pending_owner() -> Option<Principal> {
     #[allow(clippy::unwrap_used)] // unwrap desired
@@ -231,15 +225,13 @@ pub fn only_admin() -> Result<(), String> {
 }
 
 /// Checks if a principal is an admin.
-#[candid_method(query)]
 #[query]
 pub fn is_admin(admin: Principal) -> bool {
     #[allow(clippy::unwrap_used)] // unwrap desired
     ACCESS_CONTROL.with(|c| c.borrow().get().0.clone().unwrap().admins.contains(&admin))
 }
 
 /// Grants admin to a new Principal. Must be called by the `owner`.
-#[candid_method(update)]
 #[update]
 #[modifiers("only_owner")]
 pub fn grant_admin(new_admin: Principal) {
@@ -261,7 +253,6 @@ pub fn grant_admin(new_admin: Principal) {
 }
 
 /// Revokes admin from a Principal. Must be called by the `owner`.
-#[candid_method(update)]
 #[update]
 #[modifiers("only_owner")]
 pub fn revoke_admin(admin: Principal) {
@@ -276,7 +267,6 @@ pub fn revoke_admin(admin: Principal) {
 }
 
 /// Revokes admin from the caller. Must be called by the admin itself.
-#[candid_method(update)]
 #[update]
 #[modifiers("only_admin")]
 pub fn renounce_admin() {
@@ -327,7 +317,6 @@ fn is_role_admin(role_flag: u32, role: u8) -> bool {
 /// but the current caller does not have the permission to grant the role,
 /// the return value for that role is `false`.
 #[cfg(feature = "access-roles")]
-#[candid_method(update)]
 #[update]
 pub fn grant_roles(roles: Vec<u8>, principal: Principal) -> Vec<bool> {
     // caller authentication in arithmetics
@@ -362,7 +351,6 @@ pub fn grant_roles(roles: Vec<u8>, principal: Principal) -> Vec<bool> {
 /// but the current caller does not have the permission to revoke the role,
 /// the return value for that role is `false`.
 #[cfg(feature = "access-roles")]
-#[candid_method(update)]
 #[update]
 pub fn revoke_roles(roles: Vec<u8>, principal: Principal) -> Vec<bool> {
     // caller authentication arithmetics
@@ -389,7 +377,6 @@ pub fn revoke_roles(roles: Vec<u8>, principal: Principal) -> Vec<bool> {
 
 /// Returns the bitflag of roles granted to a principal.
 #[cfg(feature = "access-roles")]
-#[candid_method(query)]
 #[query]
 pub fn get_user_roles(principal: Principal) -> u32 {
     ACCESS_ROLES.with(|c| {
@@ -401,7 +388,6 @@ pub fn get_user_roles(principal: Principal) -> u32 {
 /// Checks whether a principal has a certain role.
 /// Returns a boolean indicating whether the principal has the role.
 #[cfg(feature = "access-roles")]
-#[candid_method(query)]
 #[query]
 pub fn user_has_role(role: u8, principal: Principal) -> bool {
     ACCESS_ROLES.with(|c| {
@@ -429,7 +415,6 @@ pub fn has_role(role: u8) -> Result<(), String> {
 /// Checks whether a principal has all of the specified roles.
 /// Returns a boolean indicating whether the principal has all of the roles.
 #[cfg(feature = "access-roles")]
-#[candid_method(query)]
 #[query]
 pub fn user_has_roles_all(roles: Vec<u8>, principal: Principal) -> bool {
     ACCESS_ROLES.with(|c| {
@@ -457,7 +442,6 @@ pub fn has_roles_all(roles: Vec<u8>) -> Result<(), String> {
 /// Checks whether a principal has any of the specified roles.
 /// Returns a boolean indicating whether the principal has any of the roles.
 #[cfg(feature = "access-roles")]
-#[candid_method(query)]
 #[query]
 pub fn user_has_roles_any(roles: Vec<u8>, principal: Principal) -> bool {
     ACCESS_ROLES.with(|c| {
@@ -484,7 +468,6 @@ pub fn has_roles_any(roles: Vec<u8>) -> Result<(), String> {
 
 /// Sets role admins for a role. Must be called by admins.
 #[cfg(feature = "access-roles")]
-#[candid_method(update)]
 #[update]
 #[modifiers("only_admin")]
 pub fn set_role_admins(role: u8, admins: Vec<u8>) {
@@ -503,7 +486,6 @@ pub fn set_role_admins(role: u8, admins: Vec<u8>) {
 
 /// Revokes role admins for a role. Must be called by admins.
 #[cfg(feature = "access-roles")]
-#[candid_method(update)]
 #[update]
 #[modifiers("only_admin")]
 pub fn revoke_role_admins(role: u8, admins: Vec<u8>) {

src/access_control.rs

@@ -1,6 +1,6 @@
 use crate::memory_map::*;
 use crate::types::*;
-use candid::{candid_method, CandidType};
+use candid::CandidType;
 use ic_cdk_macros::query;
 use ic_stable_structures::{DefaultMemoryImpl, StableCell};
 use std::cell::RefCell;
@@ -40,7 +40,6 @@ pub(crate) fn global_flags_init() {
 
 /// Returns the `RUSTIC_USER_PAGE_END` constant used during setup.
 /// This value is set through a environment variable and shall remain constant across versions.
-#[candid_method(query)]
 #[query]
 pub async fn get_config_user_page_end() -> u64 {
     GLOBAL_FLAGS.with(|gf| {

src/global_flags.rs

@@ -3,7 +3,6 @@
 // Re-export the macros
 #[doc(inline)]
 pub use rustic_macros::*;
-use utils::canister_caller;
 
 pub mod access_control;
 mod global_flags;
@@ -17,6 +16,12 @@ pub mod testing;
 pub mod types;
 pub mod utils;
 
+#[cfg(feature = "lifecycle")]
+use crate::lifecycle::CanisterLifecycle;
+use crate::utils::canister_caller;
+
+use candid::Principal;
+
 /// Initializes the Rustic module. Needs to be called in the init hook of every canister.
 /// # Example
 /// ```rust
@@ -59,3 +64,6 @@ pub fn rustic_post_upgrade(
     #[cfg(feature = "lifecycle")]
     crate::lifecycle::lifecycle_on_upgrade(stable_memory_bump, major_bump, minor_bump);
 }
+
+#[cfg(feature = "export-candid")]
+ic_cdk::export_candid!();

src/lib.rs

@@ -1,13 +1,13 @@
 #![cfg(feature = "lifecycle")]
 //! Canister Lifecycle Management
-//! 
+//!
 
 use crate::memory_map::*;
 #[cfg(test)]
 use crate::testing::*;
 use crate::types::*;
 use crate::utils::*;
-use candid::{candid_method, CandidType};
+use candid::CandidType;
 use ic_cdk_macros::query;
 use ic_stable_structures::{DefaultMemoryImpl, StableCell};
 use std::cell::RefCell;
@@ -89,15 +89,13 @@ pub(crate) fn lifecycle_on_upgrade(stable_memory_bump: bool, major_bump: bool, m
 
 /// Returns the current version of the canister.
 #[query]
-#[candid_method(query)]
 pub fn get_version() -> CanisterLifecycle {
     #[allow(clippy::unwrap_used)] // safe unwrap
     CANISTER_LIFECYCLE.with(|l| l.borrow().get().0.clone().unwrap())
 }
 
 /// Returns the current version of the canister as a string.
 #[query]
-#[candid_method(query)]
 pub fn get_version_text() -> String {
     #[allow(clippy::unwrap_used)] // safe unwrap
     CANISTER_LIFECYCLE.with(|l| l.borrow().get().0.clone().unwrap().to_string())

src/lifecycle.rs

@@ -15,7 +15,6 @@ use crate::global_flags::*;
 #[cfg(test)]
 use crate::testing::*;
 use crate::types::*;
-use candid::candid_method;
 use ic_cdk_macros::{query, update};
 use rustic_macros::modifiers;
 
@@ -42,15 +41,13 @@ pub fn when_paused() -> Result<(), String> {
 }
 
 /// Query method to get the current pause status.
-#[candid_method(query)]
 #[query]
 pub fn is_paused() -> bool {
     #[allow(clippy::unwrap_used)] // unwrap desired
     GLOBAL_FLAGS.with(|f| f.borrow().get().0.clone().unwrap().paused)
 }
 
 /// Pauses the canister. Can only be called by admins.
-#[candid_method(update)]
 #[update]
 #[modifiers("only_admin")]
 pub fn pause() {
@@ -65,7 +62,6 @@ pub fn pause() {
 }
 
 /// Resumes the canister. Can only be called by admins.
-#[candid_method(update)]
 #[update]
 #[modifiers("only_admin")]
 pub fn resume() {