feat/aml: locking accounts #66

fusede · 2025-04-22T13:35:17Z

See docs for AccountForceLocker:

#[ext_contract(ext_force_account_locker)]
pub trait AccountForceLocker: AccessControllable {
    /// Returns whether the given`account_id` is locked
    fn is_account_locked(&self, account_id: &AccountId) -> bool;

    /// Locks given `account_id` from modifying its own state, including
    /// token balances.
    /// Returns `false` if the account was already in locked state.
    ///
    /// Attached deposit of 1yN is required for security purposes.
    ///
    /// NOTE: this still allows for force withdrawals/transfers
    fn force_lock_account(&mut self, account_id: AccountId) -> bool;
    /// Unlocks given `account_id`.
    /// Returns `false` if the account wasn't in locked state.
    ///
    /// Attached deposit of 1yN is required for security purposes.
    fn force_unlock_account(&mut self, account_id: &AccountId) -> bool;
}

BonelessImpl · 2025-04-24T07:38:48Z

near-utils/src/panic_on_clone.rs

+        let value = "example".to_string();
+        let poc = PanicOnClone::from_ref(&value);
+        assert!(ptr::eq(&**poc, &value));
+        assert_eq!(&**poc, &value);


No test for panic behavior?

near-utils/src/lock.rs

BonelessImpl · 2025-04-24T07:45:04Z

near-utils/src/lock.rs

I think this struct needs some unit tests... too many special cases.

BonelessImpl · 2025-04-24T07:53:33Z

core/src/error.rs

+    AccountNotFound(AccountId),
+
+    #[error("account '{0}' is locked")]
+    AccountLocked(AccountId),


If I understand correctly what "locked" means here, I think the proper language is "frozen"... we "freeze" bank accounts.

BonelessImpl · 2025-04-24T08:20:48Z

tests/src/tests/defuse/accounts.rs

+    async fn is_account_locked(&self, account_id: &AccountIdRef) -> anyhow::Result<bool>;
+    async fn defuse_is_account_locked(
+        &self,
+        defuse_contract_id: &AccountId,
+        account_id: &AccountIdRef,
+    ) -> anyhow::Result<bool>;
+
+    async fn force_lock_account(&self, account_id: &AccountIdRef) -> anyhow::Result<bool>;
+    async fn defuse_force_lock_account(
+        &self,
+        defuse_contract_id: &AccountId,
+        account_id: &AccountIdRef,
+    ) -> anyhow::Result<bool>;
+    async fn force_unlock_account(&self, account_id: &AccountIdRef) -> anyhow::Result<bool>;
+    async fn defuse_force_unlock_account(
+        &self,
+        defuse_contract_id: &AccountId,
+        account_id: &AccountIdRef,
+    ) -> anyhow::Result<bool>;


I really don't think it's necessary to duplicate these methods... just one of them is enough, and specifying the smart contracts in the tests is alright.

tests/src/tests/defuse/env.rs

defuse/src/tokens/nep245.rs

BonelessImpl · 2025-04-24T08:43:02Z

defuse/src/accounts.rs

@@ -31,3 +32,23 @@ pub trait AccountManager {
    /// NOTE: MUST attach 1 yⓃ for security purposes.
    fn invalidate_nonces(&mut self, nonces: Vec<AsBase64<Nonce>>);
 }
+
+#[ext_contract(ext_force_account_locker)]
+pub trait AccountForceLocker: AccessControllable {


Besides using the word freeze instead of lock, I think this trait's name should be something like AccountLockable. If we agree on using freeze, then it's AccountFreezable.

BonelessImpl · 2025-04-24T09:34:12Z

near-utils/src/panic_on_clone.rs

+#[autoimpl(AsMut using self.0)]
+#[near(serializers = [borsh])]
+#[repr(transparent)] // needed for `transmute()` below
+pub struct PanicOnClone<T: ?Sized>(T);


Perhaps write some docs that explain the use-case of this struct, i.e., what problem is solves with a little example.

/// This struct is used as a tool to make it possible to derive borsh serialization in such a way where serialization can take over a reference and include it as if it's owned by the struct/enum being serialized. The reference can be taken in the function from_ref().

BonelessImpl · 2025-04-24T09:41:28Z

defuse/src/contract/accounts/account.rs

+                    .amount_for(&ft),
+                123,
+            );
+            borsh::to_vec(&versioned).expect("unale to serialize versioned account")


typo: unable

defuse/src/contract/accounts/account.rs

defuse/src/contract/tokens/nep245/force.rs

BonelessImpl · 2025-04-24T10:07:10Z

defuse/src/contract/tokens/nep245/resolver.rs

+                // which we want to avoid.
+                //
+                // So, since we allow locked accounts to receive incoming transfers, it means
+                // that `mt_transfer_call()` to locked recepients will always result in full


typo: recepients

defuse/src/contract/tokens/nep245/resolver.rs

BonelessImpl

Done with the first review round.

BonelessImpl · 2025-04-24T10:23:06Z

Cargo.lock

Cargo.lock is not up to date. Please run a full build then commit it again.

…ccount

BonelessImpl · 2025-05-12T05:31:09Z

borsh-utils/src/lib.rs

@@ -1,2 +1,3 @@
+pub mod r#as;


Can we call this something that doesn't use a literal prefix? Maybe ser_as?

BonelessImpl · 2025-05-12T06:08:45Z

io-utils/src/lib.rs

+}
+impl<R> ReadExt for R where R: Read {}
+
+pub struct TeeReader<R, W> {


/// A reader that writes everything it reads to the specified writer. Can bee seen as a passthrough.

/// The struct itself does not do any kind of caching. Any apparent caching is possibly done by the inner read and writer.

BonelessImpl · 2025-05-12T06:16:16Z

defuse/src/tokens/nep245.rs

@@ -48,3 +48,48 @@ pub trait MultiTokenForceWithdrawer: MultiTokenWithdrawer + AccessControllable {
        msg: Option<String>,
    ) -> PromiseOrValue<Vec<U128>>;
 }
+


/// MultiTokenCore functions, but a version that bypasses the locked/frozen state of an account.

/// All functions must be #[private] or only authorized callers

BonelessImpl · 2025-05-12T06:28:20Z

defuse/src/accounts.rs

+    /// Attached deposit of 1yN is required for security purposes.
+    ///
+    /// NOTE: this still allows for force withdrawals/transfers
+    fn force_lock_account(&mut self, account_id: AccountId) -> bool;


Instead of returning a bool here (and in unlock), we should probably just panic with a message "already locked".

BonelessImpl · 2025-05-12T06:36:59Z

defuse/src/accounts.rs

@@ -21,7 +22,7 @@ pub trait AccountManager {
    /// i.e. this key can't be used to make any actions unless it's re-created.
    ///
    /// NOTE: MUST attach 1 yⓃ for security purposes.
-    fn remove_public_key(&mut self, public_key: &PublicKey);
+    fn remove_public_key(&mut self, public_key: PublicKey);


Don't we usually prefer passing a reference?

BonelessImpl · 2025-05-12T08:16:49Z

near-utils/src/lock.rs

    #[inline]
-    pub fn as_unlocked_mut(&mut self) -> Option<&mut T> {
-        if self.locked {
+    pub const fn as_unlocked_mut(&mut self) -> Option<&mut T> {


Perhaps a better name for all "as_unlocked*" functions is "get*".

BonelessImpl · 2025-05-12T08:17:39Z

near-utils/src/lock.rs

    #[inline]
-    pub fn unlock(&mut self) -> Option<&mut T> {
-        if !self.locked {
+    pub const fn as_unlocked_or_mut(&mut self, force: bool) -> Option<&mut T> {


get_force_mut?

BonelessImpl · 2025-05-12T08:19:41Z

near-utils/src/lock.rs

    #[inline]
    pub const fn is_locked(&self) -> bool {
        self.locked
    }

+    #[must_use]
    #[inline]
    pub const fn as_locked(&self) -> Option<&T> {


Do we really need this function? What's the purpose of a function that gets while asserting the lock is activated? It should be either "I don't care about the lock" or "Get only if unlocked". This feels more like technical jargon to me.

This applies to all "as_locked" functions.

This Lock was initially made when we were writing the very first version of defuse contract, which was implementing "escrow swap" functionality. It turned out that in some particular cases you expect the lock to be locked, because some actions might be permitted only when it's locked.

Can we remove these now to make the API simpler to understand? If we need these functions in the future, we can assess whether we need them and add them if we do.

BonelessImpl · 2025-05-12T08:21:04Z

near-utils/src/lock.rs

+impl<T, As> BorshSerializeAs<Lock<T>> for Lock<As>
+where
+    As: BorshSerializeAs<T>,
+{
+    #[inline]
+    fn serialize_as<W>(source: &Lock<T>, writer: &mut W) -> io::Result<()>
+    where
+        W: io::Write,
+    {
+        Lock {
+            locked: source.locked,
+            value: AsWrap::<&T, &As>::new(&source.value),
+        }
+        .serialize(writer)
+    }
+}
+
+impl<T, As> BorshDeserializeAs<Lock<T>> for Lock<As>
+where
+    As: BorshDeserializeAs<T>,
+{
+    #[inline]
+    fn deserialize_as<R>(reader: &mut R) -> io::Result<Lock<T>>
+    where
+        R: io::Read,
+    {
+        Lock::<AsWrap<T, As>>::deserialize_reader(reader).map(|v| Lock {
+            locked: v.locked,
+            value: v.value.into_inner(),
+        })
+    }
+}


We need some serialization tests to assert the outcome.

BonelessImpl · 2025-05-15T08:23:55Z

defuse/src/contract/accounts/account.rs

+///
+/// This is safe to assume that legacy [`Account`] doesn't start with
+/// this prefix, since the first 4 bytes in legacy [`Account`] were used
+/// to detote the length of `prefix: Box<[u8]>` in [`LookupMap`] for


BonelessImpl · 2025-05-15T09:59:42Z

defuse/src/contract/accounts/account.rs

+impl BorshDeserializeAs<Lock<Account>> for MaybeVersionedAccountEntry {
+    fn deserialize_as<R>(reader: &mut R) -> io::Result<Lock<Account>>
+    where
+        R: io::Read,
+    {
+        let mut buf = Vec::new();
+        // There will always be 4 bytes for u32:
+        // * either `VERSIONED_MAGIC_PREFIX`,
+        // * or u32 for `Account.nonces.prefix`
+        let prefix = u32::deserialize_reader(&mut reader.tee(&mut buf))?;
+
+        if prefix == VERSIONED_MAGIC_PREFIX {
+            VersionedAccountEntry::deserialize_reader(reader)
+        } else {
+            Account::deserialize_reader(
+                // prepend already consumed part of the reader
+                &mut buf.chain(reader),
+            )
+            .map(Into::into)
+        }
+        .map(Into::into)
+    }
+}


Since we're defining the serialization manually anyway, isn't it better to define the serialization schema without PanicOnClone? We're crossing the barrier of "everything is just derived" to "we have to customize it"... let's go all the way and serialize the enum manually, and deserialize it manually as well. We're already doing that. It would be really awesome if we could throw out PanicOnClone.

BonelessImpl · 2025-05-15T10:05:44Z

defuse/src/contract/accounts/account.rs

+
+    #[rstest]
+    #[test]
+    fn legacy_upgrade(random_seed: Seed) {


This is an upgrade test. For such complex serialization schemes, we need fixed value tests too (serialized hex values, back and forth in both cases). This helps in avoiding bugs like the Nest thing, where we need that the complicated scheme ended with something we understand.

To illustrate what I see here: Imagine a function f(x) and its inverse g(x). The test here is kind of testing f(g(x)) = 1. But we need a test for what f(x) alone does, and what g(x) alone does too, because there are trivial cases where f(g(x)) = 1 is always true, but both f and g are broken.

IMHO, this format of testing must exist in any non-standard serialization plan.

BonelessImpl · 2025-05-15T10:55:54Z

core/src/error.rs

-    #[error("public key already exists")]
-    PublicKeyExists,
+    #[error("public key '{1}' already exists for account '{0}'")]
+    PublicKeyExists(AccountId, PublicKey),


I was hesitating, but I'll say it. I love this change. I love to always specify the parameters in errors to make debugging easier.

fusede added 13 commits April 15, 2025 18:25

feat: account locks

7acf381

wip

dfa2009

fix: check for lock in cached accounts

dedfa13

feat: impl BorshSerializeAs/BorshDeserializeAs for std types

67e4dab

wip

5a19142

feat: allow deposits/transfers to locked accounts

e21735c

fix: TODOs

557713e

chore: polish code

e56bd33

Merge branch 'main' into feat/aml

2f6f8b1

chore: make clippy happy

09ad632

chore: make clippy happy

9472461

feat: PanicOnClone tests

f2357a7

Merge branch 'main' into feat/aml

a9bb8ac

fusede marked this pull request as ready for review April 22, 2025 18:10

fusede added 2 commits April 23, 2025 01:24

refactor: better deserialization of AccountEntry

06f085e

chore: make clippy happy

e07ebe8

fusede requested a review from BonelessImpl April 23, 2025 08:23

fusede added 5 commits April 23, 2025 12:26

chore

064989b

feat: test lazy legacy Account upgrade

2c0d37d

docs

fc08d48

Merge branch 'main' into feat/aml

fda00c0

fix: view method mt_tokens_for_owner() should not respect lock

83ad807