feat: holding cap, early access whitelist, referral rewards, key factory

Cargo.toml

@@ -1,5 +1,5 @@
 [workspace]
-members = ["creator-keys"]
+members = ["creator-keys", "creator-keys-factory"]
 resolver = "2"
 
 [workspace.package]

creator-keys-factory/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "creator-keys-factory"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[lib]
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+soroban-sdk = { workspace = true }
+
+[dev-dependencies]
+soroban-sdk = { workspace = true, features = ["testutils"] }

creator-keys-factory/src/lib.rs

@@ -0,0 +1,169 @@
+#![no_std]
+//! Minimal factory that deploys `creator-keys` contract instances and keeps a
+//! registry of the deployed addresses.
+
+use soroban_sdk::{
+    contract, contracterror, contractimpl, contracttype, symbol_short, Address, BytesN, Env,
+    Symbol, Vec,
+};
+
+pub const KEY_DEPLOYED_EVENT_NAME: Symbol = symbol_short!("key_depl");
+
+#[contracterror]
+#[derive(Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Ord)]
+#[repr(u32)]
+pub enum FactoryError {
+    AlreadyInitialised = 1,
+    NotInitialised = 2,
+    Unauthorized = 3,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[contracttype]
+pub struct KeyDeployedEvent {
+    pub key: Address,
+    pub creator: Address,
+}
+
+#[derive(Clone)]
+#[contracttype]
+enum DataKey {
+    Admin,
+    WasmHash,
+    Registry,
+    Allowed(Address),
+}
+
+#[contract]
+pub struct CreatorKeysFactory;
+
+fn read_admin(env: &Env) -> Result<Address, FactoryError> {
+    env.storage()
+        .instance()
+        .get(&DataKey::Admin)
+        .ok_or(FactoryError::NotInitialised)
+}
+
+#[contractimpl]
+impl CreatorKeysFactory {
+    /// One-time setup: the admin and the uploaded `creator-keys` wasm hash to deploy.
+    pub fn initialise(env: Env, admin: Address, wasm_hash: BytesN<32>) -> Result<(), FactoryError> {
+        if env.storage().instance().has(&DataKey::Admin) {
+            return Err(FactoryError::AlreadyInitialised);
+        }
+        admin.require_auth();
+        env.storage().instance().set(&DataKey::Admin, &admin);
+        env.storage().instance().set(&DataKey::WasmHash, &wasm_hash);
+        Ok(())
+    }
+
+    /// Admin allows or disallows a creator wallet to call `deploy_key`.
+    pub fn set_creator_allowed(
+        env: Env,
+        admin: Address,
+        creator: Address,
+        allowed: bool,
+    ) -> Result<(), FactoryError> {
+        admin.require_auth();
+        if admin != read_admin(&env)? {
+            return Err(FactoryError::Unauthorized);
+        }
+        env.storage()
+            .instance()
+            .set(&DataKey::Allowed(creator), &allowed);
+        Ok(())
+    }
+
+    /// Deploys a new key contract for `creator` and records its address.
+    /// Only the admin or a whitelisted creator may call it.
+    pub fn deploy_key(
+        env: Env,
+        caller: Address,
+        creator: Address,
+        salt: BytesN<32>,
+    ) -> Result<Address, FactoryError> {
+        caller.require_auth();
+        let is_allowed: bool = env
+            .storage()
+            .instance()
+            .get(&DataKey::Allowed(caller.clone()))
+            .unwrap_or(false);
+        if caller != read_admin(&env)? && !is_allowed {
+            return Err(FactoryError::Unauthorized);
+        }
+        let wasm_hash: BytesN<32> = env
+            .storage()
+            .instance()
+            .get(&DataKey::WasmHash)
+            .ok_or(FactoryError::NotInitialised)?;
+
+        let key = env
+            .deployer()
+            .with_current_contract(salt)
+            .deploy_v2(wasm_hash, ());
+
+        let mut registry = Self::get_registry(env.clone());
+        registry.push_back(key.clone());
+        env.storage().instance().set(&DataKey::Registry, &registry);
+
+        env.events().publish(
+            (KEY_DEPLOYED_EVENT_NAME, creator.clone()),
+            KeyDeployedEvent {
+                key: key.clone(),
+                creator,
+            },
+        );
+        Ok(key)
+    }
+
+    /// Read-only view: every key contract address deployed by this factory.
+    pub fn get_registry(env: Env) -> Vec<Address> {
+        env.storage()
+            .instance()
+            .get(&DataKey::Registry)
+            .unwrap_or_else(|| Vec::new(&env))
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use super::*;
+    use soroban_sdk::testutils::Address as _;
+
+    fn setup(env: &Env) -> (CreatorKeysFactoryClient<'_>, Address) {
+        env.mock_all_auths();
+        let client = CreatorKeysFactoryClient::new(env, &env.register(CreatorKeysFactory, ()));
+        let admin = Address::generate(env);
+        client.initialise(&admin, &BytesN::from_array(env, &[7; 32]));
+        (client, admin)
+    }
+
+    #[test]
+    fn unauthorised_deploy_is_rejected() {
+        let env = Env::default();
+        let (client, _admin) = setup(&env);
+        let stranger = Address::generate(&env);
+        let salt = BytesN::from_array(&env, &[1; 32]);
+        assert_eq!(
+            client.try_deploy_key(&stranger, &stranger, &salt),
+            Err(Ok(FactoryError::Unauthorized))
+        );
+        assert_eq!(client.get_registry().len(), 0);
+    }
+
+    #[test]
+    fn only_admin_manages_allowed_creators_and_init_is_once() {
+        let env = Env::default();
+        let (client, admin) = setup(&env);
+        let stranger = Address::generate(&env);
+        assert_eq!(
+            client.try_set_creator_allowed(&stranger, &stranger, &true),
+            Err(Ok(FactoryError::Unauthorized))
+        );
+        client.set_creator_allowed(&admin, &stranger, &true);
+        assert_eq!(
+            client.try_initialise(&admin, &BytesN::from_array(&env, &[7; 32])),
+            Err(Ok(FactoryError::AlreadyInitialised))
+        );
+    }
+}

creator-keys/src/events.rs

@@ -819,6 +819,11 @@ pub const WHITELIST_ENABLED_EVENT_NAME: Symbol = symbol_short!("wl_en");
 pub const WHITELIST_DISABLED_EVENT_NAME: Symbol = symbol_short!("wl_dis");
 pub const ADDRESS_WHITELISTED_EVENT_NAME: Symbol = symbol_short!("wl_add");
 pub const ADDRESS_REMOVED_EVENT_NAME: Symbol = symbol_short!("wl_rem");
+pub const HOLDING_CAP_UPDATED_EVENT_NAME: Symbol = symbol_short!("hold_cap");
+pub const WHITELIST_UPDATED_EVENT_NAME: Symbol = symbol_short!("wl_upd");
+pub const REFERRAL_REGISTERED_EVENT_NAME: Symbol = symbol_short!("ref_reg");
+pub const REFERRAL_REWARD_ALLOCATED_EVENT_NAME: Symbol = symbol_short!("ref_rwd");
+pub const REFERRAL_REWARDS_CLAIMED_EVENT_NAME: Symbol = symbol_short!("ref_clm");
 pub const KEYS_BURNED_EVENT_NAME: Symbol = symbol_short!("burned");
 pub const SELF_FREEZE_APPLIED_EVENT_NAME: Symbol = symbol_short!("sf_add");
 pub const SELF_FREEZE_LIFTED_EVENT_NAME: Symbol = symbol_short!("sf_del");
@@ -895,6 +900,66 @@ pub fn address_removed_topics(creator: &Address) -> (Symbol, Address) {
     (ADDRESS_REMOVED_EVENT_NAME, creator.clone())
 }
 
+/// Emitted when a creator changes their per-wallet holding cap.
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[contracttype]
+pub struct HoldingCapUpdatedEvent {
+    pub creator: Address,
+    pub old_cap: Option<u32>,
+    pub new_cap: u32,
+}
+
+pub fn holding_cap_updated_topics(creator: &Address) -> (Symbol, Address) {
+    (HOLDING_CAP_UPDATED_EVENT_NAME, creator.clone())
+}
+
+/// Emitted on every early-access whitelist add (`allowed = true`) and remove.
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[contracttype]
+pub struct WhitelistUpdatedEvent {
+    pub creator: Address,
+    pub wallet: Address,
+    pub allowed: bool,
+}
+
+pub fn whitelist_updated_topics(creator: &Address) -> (Symbol, Address) {
+    (WHITELIST_UPDATED_EVENT_NAME, creator.clone())
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[contracttype]
+pub struct ReferralRegisteredEvent {
+    pub referee: Address,
+    pub referrer: Address,
+}
+
+pub fn referral_registered_topics() -> Symbol {
+    REFERRAL_REGISTERED_EVENT_NAME
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[contracttype]
+pub struct ReferralRewardAllocatedEvent {
+    pub referee: Address,
+    pub referrer: Address,
+    pub amount: i128,
+}
+
+pub fn referral_reward_allocated_topics() -> Symbol {
+    REFERRAL_REWARD_ALLOCATED_EVENT_NAME
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[contracttype]
+pub struct ReferralRewardsClaimedEvent {
+    pub referrer: Address,
+    pub amount: i128,
+}
+
+pub fn referral_rewards_claimed_topics() -> Symbol {
+    REFERRAL_REWARDS_CLAIMED_EVENT_NAME
+}
+
 #[derive(Clone, Debug, Eq, PartialEq)]
 #[contracttype]
 pub struct KeysBurnedEvent {