Save

It is sometimes helpful to prevent an account from going below a certain threshold balance. The save directive allows you to specify a minimum balance for an account, which will be deduced from the account available balance for the transaction.

// Prevent the end balance foo is never less than [USD/2 100]
save [USD/2 100] from @merchants:1234

send [USD/2 500] (
  source = @merchants:1234
  destination = @payouts:T1891G
)

In this transaction example, even if the account @merchants:1234 has an initial balance of [USD/2 500], the transaction will fail as the account post-transaction balance would otherwise be less than [USD/2 100].

Should additional source of funds is provided, the account will act as if its balance is [USD/2 100] less than it actually is:

// Prevent the end balance foo is never less than [USD/2 100]
save [USD/2 100] from @merchants:1234

send [USD/2 500] (
  source = {
    @merchants:1234
    @world
  }
  destination = @payouts:T1891G
)

[
  {
    "source": "merchants:1234",
    "destination": "payouts:T1891G",
    "amount": 400,
    "asset": "USD/2"
  },
  {
    "source": "world",
    "destination": "payouts:T1891G",
    "amount": 100,
    "asset": "USD/2"
  }
]

Insufficient funds error#

When the requested amount exceeds the available balance (after applying save), the transaction fails with an INSUFFICIENT_FUND error.

Example: Account has [GBP/2 120], save [GBP/2 100], available = [GBP/2 20]

save [GBP/2 100] from @my_account

send [GBP/2 30] (
  source = @my_account
  destination = @world
)

This fails because you're trying to send 30 but only 20 is available:

{
  "errorCode": "INSUFFICIENT_FUND",
  "errorMessage": "running numscript: script execution failed: account(s) @my_account had/have insufficient funds"
}

Using save with send [ASSET *]#

When using send [ASSET *] (send entire balance) with save, the behavior depends on the account balance:

Balance greater than save amount#

If the balance exceeds the saved amount, the transaction sends balance - saved_amount:

// Account balance: [GBP/2 120]
save [GBP/2 100] from @my_account

send [GBP/2 *] (
  source = @my_account
  destination = @world
)

Result: A transaction of [GBP/2 20] is created (120 - 100 = 20).

Balance less than or equal to save amount#

If the balance is less than or equal to the saved amount, a transaction with amount 0 is created:

// Account balance: [GBP/2 80]
save [GBP/2 100] from @my_account

send [GBP/2 *] (
  source = @my_account
  destination = @world
)

Result:

{
  "postings": [
    {
      "amount": 0,
      "asset": "GBP/2",
      "destination": "world",
      "source": "my_account"
    }
  ]
}

Multiple source accounts with save#

When using multiple sources with save, funds are taken from the saved account up to its available limit, then completed from other sources:

// @account_a balance: [USD/2 150]
save [USD/2 100] from @account_a

send [USD/2 80] (
  source = {
    @account_a
    @account_b
  }
  destination = @destination
)

Result:

• @account_a contributes [USD/2 50] (its available balance: 150 - 100)
• @account_b contributes [USD/2 30] (remainder needed)