How to apply limits to a wallet

Applying limits

A wallet can hold balance in multiple symbols. By default this balance is only limited to be at least 0. Limits allow wallets to have negative balance up to an specified amount or to have an upper limit, for example.

In order to apply limits to a wallet an intent with valid limit claims needs to be executed. For example, in order to allow wallet bank to have negative balance up to -200, for the symbol usd, the metric minBalance should be limited to -200 with an intent that looks like this:

{
    "handle": "limiting-usd-in-bank-wallet",
    "claims": [
    {
        "action": "limit",
        "metric": "minBalance",
        "wallet": {
            "handle": "bank"
        },
        "symbol": {
            "handle": "usd"
        },
        "amount": -20000
    }
    ],
    "access": []
}

Or using the ledger sdk

import { AccessAction, ClaimAction, LedgerIntent } from "@minka/ledger-sdk/types";
 
const sdk = new LedgerSdk({
	server: "<server-url>",
	ledger: "<ledger-handle>",
});
 
const limitIntent: LedgerIntent = {
    handle: 'limiting-usd-in-bank-wallet',
    claims: [
    {
        action: ClaimAction.Limit,
        metric: LimitClaimMetric.MinBalance,
        wallet: {
            handle: 'bank',
        },
            symbol: {
            handle: 'usd',
        },
        amount: -20000,
    },
    ],
    access: [
    {
        action: AccessAction.Any,
    },
    ],
}
 
await sdk.intent
    .init()
    .data(limitIntent)
    .hash()
    .sign([{keyPair}])
    .send()

Limit evaluation and atomicity

Keeping in mind that an intent (set of claims) is atomic - checks like balance limits (by default balance cannot go under 0) are applied having taken the cumulative claims of an intent in mind.

Because of this, even if one claim brings a wallet below or above their limit, if there's another claim in the same intent that brings it back within normal range, the intent will not break the limit and will succeed.

Available metrics for limiting

This is a list of available metrics for use in limit claims. Some of them might not be enabled by default and require a change of specific ledger config entries to enable for a ledger. Some configs might not be enabled server-wide, depending on which environment (shared, dedicated, test) you use.