feat: cartridge paymaster support (#22)

Author: kariy

Cargo.lock

@@ -55,8 +55,8 @@ debug = true
 inherits = "release"
 
 [workspace.dependencies]
-cainome = { git = "https://github.com/cartridge-gg/cainome", tag = "v0.4.12", features = [ "abigen-rs" ] }
-cainome-cairo-serde = { git = "https://github.com/cartridge-gg/cainome", tag = "v0.4.12" }
+cainome = { version = "0.5.0", features = [ "abigen-rs" ] }
+cainome-cairo-serde = { version = "0.1.0" }
 dojo-utils = { git = "https://github.com/dojoengine/dojo", tag = "v1.2.2" }
 
 # metrics
@@ -104,6 +104,9 @@ cairo-lang-utils = "2.11.2"
 # only under the `test_utils` feature. So we expose through this feature.
 cairo-vm = { version = "1.0.2", features = [ "test_utils" ] }
 
+# Controller PR revision until merged.
+# https://github.com/cartridge-gg/controller/pull/1454
+account_sdk = { git = "https://github.com/cartridge-gg/controller", rev = "dbbe0353d64de743739d425f8aab91ca3ac0e16f" }
 anyhow = "1.0.89"
 arbitrary = { version = "1.3.2", features = [ "derive" ] }
 assert_fs = "1.1"

Cargo.toml

@@ -288,8 +288,8 @@ pub async fn check_program_info(
     let (program_info_res, facts_registry_res) =
         tokio::join!(appchain.get_program_info().call(), appchain.get_facts_registry().call());
 
-    let actual_program_info = program_info_res?;
-    let facts_registry = facts_registry_res?;
+    let actual_program_info = program_info_res.map_err(|e| ContractInitError::Other(anyhow!(e)))?;
+    let facts_registry = facts_registry_res.map_err(|e| ContractInitError::Other(anyhow!(e)))?;
 
     if actual_program_info.layout_bridge_program_hash != LAYOUT_BRIDGE_PROGRAM_HASH {
         return Err(ContractInitError::InvalidLayoutBridgeProgramHash {

bin/katana/src/cli/init/deployment.rs

@@ -26,6 +26,3 @@ katana-provider = { workspace = true, features = [ "test-utils" ] }
 rstest.workspace = true
 similar-asserts.workspace = true
 tempfile.workspace = true
-
-[features]
-controller = [ "katana-primitives/controller" ]

crates/chain-spec/Cargo.toml

@@ -269,8 +269,6 @@ mod tests {
     use katana_primitives::genesis::allocation::{
         GenesisAccount, GenesisAccountAlloc, GenesisContractAlloc,
     };
-    #[cfg(feature = "controller")]
-    use katana_primitives::genesis::constant::{CONTROLLER_ACCOUNT_CLASS, CONTROLLER_CLASS_HASH};
     use katana_primitives::genesis::constant::{
         DEFAULT_ACCOUNT_CLASS, DEFAULT_ACCOUNT_CLASS_HASH,
         DEFAULT_ACCOUNT_CLASS_PUBKEY_STORAGE_SLOT, DEFAULT_ACCOUNT_COMPILED_CLASS_HASH,
@@ -290,8 +288,6 @@ mod tests {
             (DEFAULT_LEGACY_UDC_CLASS_HASH, DEFAULT_LEGACY_UDC_CLASS.clone().into()),
             (DEFAULT_LEGACY_ERC20_CLASS_HASH, DEFAULT_LEGACY_ERC20_CLASS.clone().into()),
             (DEFAULT_ACCOUNT_CLASS_HASH, DEFAULT_ACCOUNT_CLASS.clone().into()),
-            #[cfg(feature = "controller")]
-            (CONTROLLER_CLASS_HASH, CONTROLLER_ACCOUNT_CLASS.clone().into()),
         ]);
 
         let allocations = [
@@ -383,11 +379,7 @@ mod tests {
 
         similar_asserts::assert_eq!(actual_block, expected_block);
 
-        if cfg!(feature = "controller") {
-            assert!(actual_state_updates.classes.len() == 4);
-        } else {
-            assert!(actual_state_updates.classes.len() == 3);
-        }
+        assert!(actual_state_updates.classes.len() == 3);
 
         assert_eq!(
             actual_state_updates
@@ -460,21 +452,6 @@ mod tests {
             "The default oz account contract sierra class should be declared"
         );
 
-        #[cfg(feature = "controller")]
-        {
-            assert_eq!(
-                actual_state_updates.state_updates.declared_classes.get(&CONTROLLER_CLASS_HASH),
-                Some(&CONTROLLER_ACCOUNT_CLASS.clone().compile().unwrap().class_hash().unwrap()),
-                "The controller account class should be declared"
-            );
-
-            assert_eq!(
-                actual_state_updates.classes.get(&CONTROLLER_CLASS_HASH),
-                Some(&*CONTROLLER_ACCOUNT_CLASS),
-                "The controller account contract sierra class should be declared"
-            );
-        }
-
         // check that all contract allocations exist in the state updates
 
         assert_eq!(

crates/chain-spec/src/dev.rs

@@ -33,6 +33,11 @@ assert_matches.workspace = true
 starknet.workspace = true
 
 [features]
-default = [ "server", "slot" ]
+cartridge = [
+	"dep:katana-slot-controller",
+	"katana-node/cartridge",
+	"katana-rpc/cartridge",
+]
+default = [ "cartridge", "server", "slot" ]
 server = [  ]
-slot = [ "dep:katana-slot-controller", "katana-chain-spec/controller" ]
+slot = [  ]

crates/cli/Cargo.toml

@@ -17,6 +17,7 @@ use katana_node::config::dev::{DevConfig, FixedL1GasPriceConfig};
 use katana_node::config::execution::ExecutionConfig;
 use katana_node::config::fork::ForkingConfig;
 use katana_node::config::metrics::MetricsConfig;
+use katana_node::config::paymaster::PaymasterConfig;
 use katana_node::config::rpc::RpcConfig;
 #[cfg(feature = "server")]
 use katana_node::config::rpc::{RpcModuleKind, RpcModulesList};
@@ -117,6 +118,10 @@ pub struct NodeArgs {
 
     #[command(flatten)]
     pub explorer: ExplorerOptions,
+
+    #[cfg(feature = "cartridge")]
+    #[command(flatten)]
+    pub cartridge: CartridgeOptions,
 }
 
 impl NodeArgs {
@@ -167,6 +172,25 @@ impl NodeArgs {
         // the messagign config will eventually be removed slowly.
         let messaging = if cs_messaging.is_some() { cs_messaging } else { self.messaging.clone() };
 
+        #[cfg(feature = "cartridge")]
+        {
+            let paymaster = self.cartridge_config();
+
+            Ok(Config {
+                db,
+                dev,
+                rpc,
+                chain,
+                metrics,
+                forking,
+                execution,
+                messaging,
+                paymaster,
+                sequencing,
+            })
+        }
+
+        #[cfg(not(feature = "cartridge"))]
         Ok(Config { metrics, db, dev, rpc, chain, execution, sequencing, messaging, forking })
     }
 
@@ -181,7 +205,8 @@ impl NodeArgs {
     fn rpc_config(&self) -> Result<RpcConfig> {
         #[cfg(feature = "server")]
         {
-            let modules = if let Some(modules) = &self.server.http_modules {
+            #[allow(unused_mut)]
+            let mut modules = if let Some(modules) = &self.server.http_modules {
                 // TODO: This check should be handled in the `katana-node` level. Right now if you
                 // instantiate katana programmatically, you can still add the dev module without
                 // enabling dev mode.
@@ -204,6 +229,14 @@ impl NodeArgs {
                 modules
             };
 
+            // The cartridge rpc must be enabled if the paymaster is enabled.
+            // We put it here so that even when the individual api are explicitly specified
+            // (ie `--rpc.api`) we guarantee that the cartridge rpc is enabled.
+            #[cfg(feature = "cartridge")]
+            if self.cartridge.paymaster {
+                modules.add(RpcModuleKind::Cartridge);
+            }
+
             let cors_origins = self.server.http_cors_origins.clone();
 
             Ok(RpcConfig {
@@ -248,17 +281,18 @@ impl NodeArgs {
                 chain_spec.genesis.sequencer_address = *DEFAULT_SEQUENCER_ADDRESS;
             }
 
-            // generate dev accounts
+            // Generate dev accounts.
+            // If `cartridge` is enabled, the first account will be the paymaster.
             let accounts = DevAllocationsGenerator::new(self.development.total_accounts)
                 .with_seed(parse_seed(&self.development.seed))
                 .with_balance(U256::from(DEFAULT_PREFUNDED_ACCOUNT_BALANCE))
                 .generate();
 
             chain_spec.genesis.extend_allocations(accounts.into_iter().map(|(k, v)| (k, v.into())));
 
-            #[cfg(feature = "slot")]
-            if self.slot.controller {
-                katana_slot_controller::add_controller_account(&mut chain_spec.genesis)?;
+            #[cfg(feature = "cartridge")]
+            if self.cartridge.controllers || self.cartridge.paymaster {
+                katana_slot_controller::add_controller_classes(&mut chain_spec.genesis);
             }
 
             Ok((Arc::new(ChainSpec::Dev(chain_spec)), None))
@@ -328,6 +362,15 @@ impl NodeArgs {
         None
     }
 
+    #[cfg(feature = "cartridge")]
+    fn cartridge_config(&self) -> Option<PaymasterConfig> {
+        if self.cartridge.paymaster {
+            Some(PaymasterConfig { cartridge_api_url: self.cartridge.api.clone() })
+        } else {
+            None
+        }
+    }
+
     /// Parse the node config from the command line arguments and the config file,
     /// and merge them together prioritizing the command line arguments.
     pub fn with_config_file(mut self) -> Result<Self> {
@@ -389,6 +432,11 @@ impl NodeArgs {
             }
         }
 
+        #[cfg(feature = "cartridge")]
+        {
+            self.cartridge.merge(config.cartridge.as_ref());
+        }
+
         Ok(self)
     }
 }
@@ -676,4 +724,39 @@ chain_id.Named = "Mainnet"
 
         assert!(config.rpc.apis.contains(&RpcModuleKind::Dev));
     }
+
+    #[cfg(feature = "cartridge")]
+    #[test]
+    fn cartridge_paymaster() {
+        let args = NodeArgs::parse_from(["katana", "--cartridge.paymaster"]);
+        let config = args.config().unwrap();
+
+        // Verify cartridge module is automatically enabled
+        assert!(config.rpc.apis.contains(&RpcModuleKind::Cartridge));
+
+        // Test with paymaster explicitly specified in RPC modules
+        let args =
+            NodeArgs::parse_from(["katana", "--cartridge.paymaster", "--http.api", "starknet"]);
+        let config = args.config().unwrap();
+
+        // Verify cartridge module is still enabled even when not in explicit RPC list
+        assert!(config.rpc.apis.contains(&RpcModuleKind::Cartridge));
+        assert!(config.rpc.apis.contains(&RpcModuleKind::Starknet));
+
+        // Verify that all the Controller classes are added to the genesis
+        for (_, class) in katana_slot_controller::CONTROLLERS.iter() {
+            assert!(config.chain.genesis().classes.get(&class.hash).is_some());
+        }
+
+        // Test without paymaster enabled
+        let args = NodeArgs::parse_from(["katana"]);
+        let config = args.config().unwrap();
+
+        // Verify cartridge module is not enabled by default
+        assert!(!config.rpc.apis.contains(&RpcModuleKind::Cartridge));
+
+        for (_, class) in katana_slot_controller::CONTROLLERS.iter() {
+            assert!(config.chain.genesis().classes.get(&class.hash).is_none());
+        }
+    }
 }

crates/cli/src/args.rs

@@ -25,6 +25,8 @@ pub struct NodeArgsConfig {
     pub server: Option<ServerOptions>,
     #[cfg(feature = "server")]
     pub metrics: Option<MetricsOptions>,
+    #[cfg(feature = "cartridge")]
+    pub cartridge: Option<CartridgeOptions>,
 }
 
 impl NodeArgsConfig {
@@ -71,6 +73,15 @@ impl TryFrom<NodeArgs> for NodeArgsConfig {
                 if args.metrics == MetricsOptions::default() { None } else { Some(args.metrics) };
         }
 
+        #[cfg(feature = "cartridge")]
+        {
+            node_config.cartridge = if args.cartridge == CartridgeOptions::default() {
+                None
+            } else {
+                Some(args.cartridge)
+            };
+        }
+
         Ok(node_config)
     }
 }

crates/cli/src/file.rs

@@ -369,7 +369,7 @@ pub struct LoggingOptions {
     #[arg(default_value_t = LogFormat::Full)]
     pub log_format: LogFormat,
 }
-#[derive(Debug, Args, Clone, Serialize, Deserialize, PartialEq)]
+#[derive(Debug, Args, Default, Clone, Serialize, Deserialize, PartialEq)]
 #[command(next_help_heading = "Gas Price Oracle Options")]
 pub struct GasPriceOracleOptions {
     /// The L1 ETH gas price. (denominated in wei)
@@ -397,17 +397,6 @@ pub struct GasPriceOracleOptions {
     pub l1_strk_data_gas_price: Option<NonZeroU128>,
 }
 
-impl Default for GasPriceOracleOptions {
-    fn default() -> Self {
-        Self {
-            l1_eth_gas_price: None,
-            l1_strk_gas_price: None,
-            l1_eth_data_gas_price: None,
-            l1_strk_data_gas_price: None,
-        }
-    }
-}
-
 #[cfg(feature = "slot")]
 #[derive(Debug, Args, Clone, Serialize, Deserialize, Default, PartialEq)]
 #[command(next_help_heading = "Slot options")]
@@ -417,6 +406,63 @@ pub struct SlotOptions {
     pub controller: bool,
 }
 
+#[cfg(feature = "cartridge")]
+#[derive(Debug, Args, Clone, Serialize, Deserialize, PartialEq)]
+#[command(next_help_heading = "Cartridge options")]
+pub struct CartridgeOptions {
+    /// Declare all versions of the Controller class at genesis. This is implictly enabled if
+    /// `--cartridge.paymaster` is provided.
+    #[arg(long = "cartridge.controllers")]
+    pub controllers: bool,
+
+    /// Whether to use the Cartridge paymaster.
+    /// This has the cost to call the Cartridge API to check
+    /// if a controller account exists on each estimate fee call.
+    ///
+    /// Mostly used for local development using controller, and must be
+    /// disabled for slot deployments.
+    #[arg(long = "cartridge.paymaster")]
+    #[arg(default_value_t = false)]
+    #[serde(default)]
+    pub paymaster: bool,
+
+    /// The root URL for the Cartridge API.
+    ///
+    /// This is used to fetch the calldata for the constructor of the given controller
+    /// address (at the moment). Must be configurable for local development
+    /// with local cartridge API.
+    #[arg(long = "cartridge.api", requires = "paymaster")]
+    #[arg(default_value = "https://api.cartridge.gg")]
+    #[serde(default = "default_api_url")]
+    pub api: Url,
+}
+
+#[cfg(feature = "cartridge")]
+impl CartridgeOptions {
+    pub fn merge(&mut self, other: Option<&Self>) {
+        if let Some(other) = other {
+            if self.paymaster == default_paymaster() {
+                self.paymaster = other.paymaster;
+            }
+
+            if self.api == default_api_url() {
+                self.api = other.api.clone();
+            }
+        }
+    }
+}
+
+#[cfg(feature = "cartridge")]
+impl Default for CartridgeOptions {
+    fn default() -> Self {
+        CartridgeOptions {
+            controllers: false,
+            paymaster: default_paymaster(),
+            api: default_api_url(),
+        }
+    }
+}
+
 #[derive(Debug, Default, Args, Clone, Serialize, Deserialize, PartialEq)]
 #[command(next_help_heading = "Explorer options")]
 pub struct ExplorerOptions {
@@ -519,3 +565,11 @@ where
         None => serializer.serialize_none(),
     }
 }
+
+fn default_paymaster() -> bool {
+    false
+}
+
+fn default_api_url() -> Url {
+    Url::parse("https://api.cartridge.gg").expect("qed; invalid url")
+}