Standard freeze() func for token interface

[orbitlens]

Multiple DeFi usage scenarios (DAO, trading, bridges, etc.) require locking some amount of tokens on the account/contract balance in order to use them later. A standard approve() function can set the spending token allowance but it cannot ensure that the contract will be able to spend it in the future because a user can transfer/spend/lock these tokens, so the actual balance during the transaction execution might be lower than the allowance. Users can also approve several conflicting allowances to different contracts. This case is similar to the issue addressed by the CAP-3 (Asset-backed offers).

Currently, the only way to overcome this problem is to transfer funds to the contract that will temporary lock them. It's potentially less secure than freezing tokens on the address balance, and not ideal from the tax reporting perspective since transferring funds to some contract even solely for the temporary lockup purpose may be considered a taxable event depending on the jurisdiction.

It would be nice to have a freeze() function in both SAC and standard token interface to provide the ability for the contracts to temporary lock user funds within a pre-approved allowance amount.

/// Temporary freeze specified amount of tokens preventing an owner to transfer/burn them.
///
/// # Arguments
///
/// * `from` - The address holding the balance of tokens.
/// * `spender` - The address on behalf of which the tokens are frozen.
/// * `amount` - The tokens to freeze. Cannot be greater than the current token allowance.
/// * `expiration_ledger` - The ledger number where the lockup period expires. 
///    Cannot be less than the current ledger number unless the amount is being set to 0.
///    Cannot be greater than the expiration_ledger specified in the current token allowance.
///    An expired entry (where expiration_ledger < the current ledger number)
///    should be treated as token unlock.
///
/// # Events
///
/// Emits an event with topics `["freeze", from: Address, spender: Address], data = [amount: i128, expiration_ledger: u32]`
fn freeze(env: Env, from: Address, spender: Address, amount: i128, expiration_ledger: u32);

/// Returns the number of tokens frozen by `spender` on the `from` balance.
///
/// # Arguments
///
/// * `from` - The address holding the balance of tokens.
/// * `spender` - The address that have frozen the tokens.
fn frozen(env: Env, from: Address, spender: Address) -> i128;

A spender should be allowed to freeze tokens only if it previously received allowance to spend these tokens, and for the period not exceeding the current allowance. Semantics should be similar to the approve() func:

• Calling freeze() for the first time with non-zero amount creates a record containing the amount of frozen tokens and expiration_ledger.
• Calling freeze() func with a zero amount or when expiration_ledger<current_ledger should unlock all previously locked tokens.
• Calling freeze() when the spender already has some frozen allowance modifies currently frozen amount (but never exceeding current allowance limits).

Unlike the approve() func, calling freeze() should implicitly check the actually available tokens balance and prevent the spender from locking more tokens that currently available. Before the spender will be able to use frozen tokens it must call freeze() to reduce the frozen amount or unfreeze it completely, so that the amount of tokens the spender will be able to transfer/burn using the transfer_from() func should be equal to min(current_balance, allowance - frozen).

Freezing the tokens on the account balance should increase its selling_liabilities. This way Classic operations (transfers, SDEX operations) will be unable to use frozen tokens.

Potential applications: cross-chain bridges, DAO voting, orderbook-based DEXes, escrow contracts, non-custodial wallets.

---

It's just an idea at this point. Obviously, not comprehensive enough.
Would love to hear some feedback on this before starting working on the formal proposal.

[dmkozh]

This seems like it may be pretty useful, although I don't have a great perspective into all the use cases.

I do have some questions regarding the proposed semantics. Specifically, the interaction between the 'frozen' allowance and transfer_from is not clear. I believe that in order for things to work properly, freeze has to create a new, separate type of allowance (otherwise, it seems like it's possible for spender to 'freeze' the token, but not necessarily to actually be able to use it). If that's the case, then I wonder why not skip the allowance step completely.

Instead, we could e.g. make freeze to require auth from from when the amount of the allowance is increased and from spender when allowance is decreased (i.e. spender can't freeze more without the user agreement, but the user can't unfreeze their tokens without spender's agreement). If that's too confusing, freeze may only require auth for from and disallow reducing the amount/time for the token to be frozen. Then we could have another function unfreeze that requires auth from spender and removes (or reduces) the existing frozen allowance.

In case if we keep using transfer_from there is also some ambiguity around which allowance has to be spent first. I would imagine the frozen one, but if we think that this rather arbitrary decision may be problematic, it might be better to introduce a new function that spends specifically the frozen allowance.

[orbitlens]

Having two separate allowances might unnecessarily complicate the logic. In my proposal frozen amount is directly related to the allowance (maybe even stored together depending on the implementation). The spender can freeze tokens only within the previously approved amount and expiration_ledger. So transfer_from() can transfer no more than allowance - frozen tokens. There's no conflict between frozen and allowance in this case -- the spender can only spend allowance that is not frozen. Basically, it should work similar to how a bank performs account operations.

The tricky part regarding the authorization here is that calling freeze() should require from address authentication when the frozen balance increases, but should not require auth when it decreases (semantically it means that the spender "unfreezes" part of the locked balance or all of it). I don't have any expertise in the authorization logic, so if it's not possible to achieve such a behavior, we can define an additional unfreeze(env: Env, from: Address, spender: Address, amount: i128) func specifically for this.

Let's take, for example, a DEX order flow (DAO or bridging might be more demonstrative but orderbook allows to highlight the example of a partial unfreeze).

1. User initiates a new limit order creation (sell 100 XLM -> USDC), active 1 week from now (let's say, till ledger 50000).
   Orderbook contract invokes approve(seller, orderbook, 100, 50000) first, creating a new allowance record for 100 XLM
   and freeze(seller, orderbook, 100, 50000) to lock these funds for the order.
   Contract requires auth from the seller.
   XLM allowance=100, frozen=100 for the orderbook contract as spender.
2. Someone else executes the trade against the order, buying 40 XLM.
   Orderbook contract invokes freeze(seller, orderbook, 60, 50000) reflecting the reduction of the frozen amount
   and then transfer_from(orderbook,seller,buyer,40) to transfer sold amount to the buyer.
   Contract does not require auth from the seller since the frozen amount is reduced.
   XLM allowance=60, frozen=60.
3. User creates another order (sell 20 XLM -> AQUA), active 1 month from now (till ledger 60000).
   Orderbook contract invokes approve(seller, orderbook, 80, 60000) (allowance and expiration_ledger increased)
   and freeze(seller, orderbook, 80, 60000) to reflects total amount locked by 2 active orders.
   Contract requires auth from the seller.
   XLM allowance=80, frozen=80.
4. User cancels both orders.
   Orderbook contract invokes approve(seller, orderbook, 0, 0) and freeze(seller, orderbook, 0, 0).
   Contract requires auth from the seller.
   XLM allowance=0, frozen=0.

[tomerweller]

On the benefit side, I agree that this might be useful for tax reporting. Although I'd love to get some more signal. Is there any prior art for something like this on other chains?

On the cost side, my knee jerk reaction is to resist complexity, especially when it sets us apart from other platforms. If we share this reporting challenge with erc20 assets, for example, then it's likely that there are tax reporting solutions that already handle these cases.

I acknowledge that this complexity and balance bifurcation already exists with XLM balances (base reserve, dex liabilities) and TrustLines (dex liabilities). But

• (a) I would prefer to move away from complexity, not take on more. Currently custom account balances and custom token balances do not have a separation of total balance from spendable balance, which I think is a win and we should be careful of sacrificing.
• (b) with classic dex liabilities there is a guarantee that an account has full control of it's liabilities. With Soroban it's in control of another smart contract so there are no such guarantees. So effectively a user will have a portion of their balance that is completely out of their control. That doesn't seem right.

[overcat]

Setting aside tax considerations, I also prefer not to add complexity and instead let third-party contracts handle it based on their own needs.

Currently, the only way to overcome this problem is to transfer funds to the contract that will temporarily lock them. It's potentially less secure than freezing tokens on the address balance.

We should only approve contracts we trust. I believe that if a contract has risks, there will be issues no matter which method is used.

[leighmcculloch]

Something for us to consider is that this is building more custom logic into all tokens, rather than leaning into contracts as a way to bring custom logic to all tokens. The later is interesting because the freeze logic can take many shapes and forms if it can be defined independent of tokens.

I don't love to suggest this because it may be very much over-engineered, but if balance holders could hook in other contracts into their balance on any transfer, they could achieve things like freezing without freezing needing to be added to every token, or the token standard.

How I imagine this would happen is a balance holder could register a "transfer hook" that would either approve or deny the transfer. There's quite a lot to figure out if we went this route, so I'm not proposing any specific design here, just that "hooks" would make this possible without the token standard having to buy into this feature specifically.

[dmkozh]

I think transfer_from is generally not quite idiomatic for Soroban. There is already a mechanism for 'hooks' in custom accounts. But I also don't quite see what issues would this solve here - this still can't ensure that token can be available to the spender.

[leighmcculloch]

Right, custom account hooks could have also provided the transfer_from behavior, but yet transfer_from still exists because there's value in capturing that at the token interface itself. Custom accounts are very flexible, but the barrier to leveraging them is higher, esp in terms of integrating into existing G/C accounts.

An example for how to implement freeze with custom accounts may help. It could be a good contract to add to https://github.com/stellar/soroban-examples.

[dmkozh]

What I still don't quite understand with this proposal is requirements for the freeze. Reading the initial post made me think that the intention is for the source account to not be able to do anything about the frozen tokens in order to guarantee that the spender can spend them. This is by definition impossible to implement with a custom account. But if the freeze is just for prevent accidental overspending, it could be implemented at the custom account level as well. I agree though that it's still much less flexible than a protocol level solution (especially for SAC) and doesn't quite solve the original issue in this proposal.

I was initially unsure if hooks can actually do more than custom accounts authorization-wise (which is why I've brought them up in the first place), but after thinking about this more, it does seem possible to come up with something potentially working. Not sure if that's actually necessary though.