Contract Upgrade Procedure

// Factory contract — new function for operator-controlled upgrade
pub fn set_wasm_hash(env: Env, new_wasm_hash: BytesN<32>) {
    // Only the factory deployer/operator can call this
    // Requires auth of the operator address stored at init time
    env.current_contract_address().require_auth();
    storage::set_wasm_hash(&env, &new_wasm_hash);
}

# 1. Build the new WASM
cd contracts/invisible_wallet
cargo build --target wasm32-unknown-unknown --release
 
# 2. Upload WASM and capture its hash
stellar contract upload \
  --wasm target/wasm32-unknown-unknown/release/invisible_wallet.wasm \
  --source <OPERATOR_SECRET> \
  --rpc-url https://soroban-testnet.stellar.org \
  --network-passphrase "Test SDF Network ; September 2015"
 
# 3. Update the factory's stored hash (output hash from step 2)
stellar contract invoke \
  --id <FACTORY_CONTRACT_ID> \
  --fn set_wasm_hash \
  --source <OPERATOR_SECRET> \
  --rpc-url https://soroban-testnet.stellar.org \
  --network-passphrase "Test SDF Network ; September 2015" \
  -- \
  --new_wasm_hash <HEX_WASM_HASH>

// Host function — called from within the wallet contract
env.deployer().update_current_contract_wasm(new_wasm_hash);

/// Upgrade this wallet's WASM to a new version.
/// Only callable by the wallet signer (passkey required).
pub fn upgrade(env: Env, new_wasm_hash: BytesN<32>) {
    env.current_contract_address().require_auth();
    env.deployer().update_current_contract_wasm(new_wasm_hash);
}

# 1. Build and upload new WASM (same as Path 1)
cd contracts/invisible_wallet
cargo build --target wasm32-unknown-unknown --release
stellar contract upload \
  --wasm target/wasm32-unknown-unknown/release/invisible_wallet.wasm \
  --source <FEE_PAYER_SECRET> \
  --rpc-url https://soroban-testnet.stellar.org \
  --network-passphrase "Test SDF Network ; September 2015"
 
# 2. Build the upgrade transaction (from the Veil wallet UI or Agent)
# The SDK's signAuthEntry flow handles the passkey challenge
# See sdk/src/useInvisibleWallet.ts for the sign-and-submit pattern
 
# 3. Submit the upgrade (using stellar CLI as operator)
stellar contract invoke \
  --id <WALLET_CONTRACT_ID> \
  --fn upgrade \
  --source <FEE_PAYER_SECRET> \
  --rpc-url https://soroban-testnet.stellar.org \
  --network-passphrase "Test SDF Network ; September 2015" \
  -- \
  --new_wasm_hash <HEX_WASM_HASH>

// ❌ BREAKING — reordering variants changes the storage key discriminant
#[contracttype]
pub enum DataKey {
    Signers,         // Was index 0, now index 0 (ok if nothing inserted before)
    // ...but inserting Nonce here would shift RpId and Origin's discriminant
    Guardian,
}
 
// ✅ SAFE — append new variants at the end
#[contracttype]
pub enum DataKey {
    Signers,
    Guardian,
    RpId,
    Origin,
    // Existing variants above — never reorder
    Nonce,
    RecoveryPending,
    Allowance(AllowanceKey),
    // New variants go HERE — at the end
}

// ❌ BREAKING — removing a variant shifts all subsequent discriminant values
// If you remove DataKey::Nonce, the stored Nonce value cannot be read
 
// ❌ BREAKING — renaming a variant
// DataKey::Signers → DataKey::AuthorizedKeys changes the discriminant
 
// ❌ BREAKING — changing a struct field type
// pub struct Allowance { amount: i128, expiry: Option<u64> }
// → pub struct Allowance { amount: i128, expiry: u64 } // wrong type

// ✅ SAFE — adding optional fields to a struct (if handled via migration)
// Old: pub struct Allowance { amount: i128, expiry: Option<u64> }
// New: pub struct Allowance { amount: i128, expiry: Option<u64>, max_per_tx: Option<i128> }
// Only safe if you handle the old format in a migration step

#[contracttype]
pub enum DataKey {
    Signers,
    Guardian,
    RpId,
    Origin,
    Nonce,
    RecoveryPending,
    Allowance(AllowanceKey),
    SessionKeyAcl(BytesN<32>),
    // NEW — append at the end
    EmergencyPause,
}

/// Pause all non-recovery operations. Only callable by a wallet signer.
pub fn emergency_pause(env: Env) {
    env.current_contract_address().require_auth();
    env.storage().instance().set(&DataKey::EmergencyPause, &true);
}
 
/// Resume normal operations.
pub fn emergency_unpause(env: Env) {
    env.current_contract_address().require_auth();
    env.storage().instance().set(&DataKey::EmergencyPause, &false);
}

pub fn __check_auth(...) -> Result<(), WalletError> {
    // Check pause flag early — reject all auth if paused
    if env.storage().instance().has(&DataKey::EmergencyPause) {
        let paused: bool = env.storage().instance().get(&DataKey::EmergencyPause).unwrap();
        if paused {
            return Err(WalletError::ContractPaused); // New error variant
        }
    }
    // ... rest of auth logic
}

cd contracts/invisible_wallet
cargo build --target wasm32-unknown-unknown --release
 
NEW_HASH=$(stellar contract upload \
  --wasm target/wasm32-unknown-unknown/release/invisible_wallet.wasm \
  --source <OPERATOR_SECRET> \
  --rpc-url https://soroban-testnet.stellar.org \
  --network-passphrase "Test SDF Network ; September 2015" \
  --output hash \
  2>&1 | tail -1)
 
echo "New WASM hash: $NEW_HASH"

stellar contract invoke \
  --id <FACTORY_ID> \
  --fn set_wasm_hash \
  --source <OPERATOR_SECRET> \
  --rpc-url https://soroban-testnet.stellar.org \
  --network-passphrase "Test SDF Network ; September 2015" \
  -- \
  --new_wasm_hash "$NEW_HASH"
 
echo "Factory WASM hash updated — new wallets will use the new code."

// scripts/batch-upgrade.ts
import { Keypair, rpc as SorobanRpc, Contract, TransactionBuilder, BASE_FEE, nativeToScVal } from '@stellar/stellar-sdk';
 
async function upgradeWallet(
  rpcUrl: string,
  networkPassphrase: string,
  walletAddress: string,
  feePayer: Keypair,
  newWasmHash: string,
) {
  const server = new SorobanRpc.Server(rpcUrl);
  const source = await server.getAccount(feePayer.publicKey());
  const wallet = new Contract(walletAddress);
  const hashBytes = Buffer.from(newWasmHash, 'hex');
 
  const tx = new TransactionBuilder(source, {
    fee: BASE_FEE,
    networkPassphrase,
  })
    .addOperation(wallet.call('upgrade', nativeToScVal(hashBytes, { type: 'bytes' })))
    .setTimeout(30)
    .build();
 
  const sim = await server.simulateTransaction(tx);
  if (SorobanRpc.Api.isSimulationError(sim)) throw new Error(`Sim failed: ${sim.error}`);
 
  const assembled = SorobanRpc.assembleTransaction(tx, sim).build();
  assembled.sign(feePayer);
 
  const sendResult = await server.sendTransaction(assembled);
  if (sendResult.status === 'ERROR') throw new Error(`Send failed: ${sendResult.errorResult?.toXDR('base64')}`);
 
  // Poll for confirmation
  for (let i = 0; i < 30; i++) {
    const result = await server.getTransaction(sendResult.hash);
    if (result.status !== SorobanRpc.Api.GetTransactionStatus.NOT_FOUND) {
      return result;
    }
    await new Promise(r => setTimeout(r, 1000));
  }
  throw new Error('Timeout waiting for confirmation');
}
 
// Usage
const wallets = ['C...1', 'C...2', 'C...3']; // fetch from your deployment list
const feePayer = Keypair.fromSecret('S...');
for (const addr of wallets) {
  console.log(`Upgrading ${addr}...`);
  await upgradeWallet(
    'https://soroban-testnet.stellar.org',
    'Test SDF Network ; September 2015',
    addr,
    feePayer,
    'abcdef...', // new WASM hash
  );
  console.log(`  ✅ ${addr} upgraded`);
}

# Check that the new function exists
stellar contract invoke \
  --id <WALLET_ADDRESS> \
  --fn emergency_pause \
  --source <FEE_PAYER_SECRET> \
  --rpc-url https://soroban-testnet.stellar.org \
  --network-passphrase "Test SDF Network ; September 2015"
 
# Verify old state is intact (signers, guardian, nonce)
stellar contract invoke \
  --id <WALLET_ADDRESS> \
  --fn get_nonce \
  --rpc-url https://soroban-testnet.stellar.org \
  --network-passphrase "Test SDF Network ; September 2015"

# Archive the current WASM binary and its hash
cp target/wasm32-unknown-unknown/release/invisible_wallet.wasm \
  releases/invisible_wallet-v0.1.0.wasm
sha256sum releases/invisible_wallet-v0.1.0.wasm | tee releases/invisible_wallet-v0.1.0.sha256
 
# Record the hash used by the factory
stellar contract invoke \
  --id <FACTORY_ID> \
  --fn get_wasm_hash \
  --rpc-url https://soroban-testnet.stellar.org \
  --network-passphrase "Test SDF Network ; September 2015"

# 1. Build the old WASM from the previous git tag
git checkout v0.1.0
cargo build --target wasm32-unknown-unknown --release
 
# 2. Upload it (gets a new hash — same code, different upload)
OLD_UPLOAD_HASH=$(stellar contract upload \
  --wasm target/wasm32-unknown-unknown/release/invisible_wallet.wasm \
  --source <OPERATOR_SECRET> \
  --rpc-url https://soroban-testnet.stellar.org \
  --network-passphrase "Test SDF Network ; September 2015" \
  --output hash \
  2>&1 | tail -1)
 
# 3. Point factory to old hash
stellar contract invoke \
  --id <FACTORY_ID> \
  --fn set_wasm_hash \
  --source <OPERATOR_SECRET> \
  --rpc-url https://soroban-testnet.stellar.org \
  --network-passphrase "Test SDF Network ; September 2015" \
  -- \
  --new_wasm_hash "$OLD_UPLOAD_HASH"
 
# 4. Roll back individual wallets as needed
# (re-run batch-upgrade.ts with OLD_UPLOAD_HASH)