Tallied Approval Amounts

Limit transfer amounts using increment-only trackers with thresholds.

Interface

interface ApprovalCriteria<T extends NumberType> {
    approvalAmounts?: ApprovalAmounts<T>;
}

How It Works

Specify maximum amounts that can be transferred using four tracker types:

• Overall (trackerType = "overall"): Universal limit for all transfers

• Per To Address (trackerType = "to"): Limit per unique recipient

• Per From Address (trackerType = "from"): Limit per unique sender

• Per Initiated By Address (trackerType = "initiatedBy"): Limit per unique initiator

"0" means unlimited and not tracked. "N" means max N amount allowed.

Example

{
    "approvalAmounts": {
        "overallApprovalAmount": "1000",
        "perFromAddressApprovalAmount": "0",
        "perToAddressApprovalAmount": "0",
        "perInitiatedByAddressApprovalAmount": "10",
        "amountTrackerId": "uniqueID"
    }
}

Tracker Types

Overall Tracker

• ID: 1-collection- -approvalId-uniqueID-overall-

• Behavior: Increments for all transfers regardless of sender/recipient/initiator

• Use Case: Global collection limits

Per-To Address Tracker

• ID: 1-collection- -approvalId-uniqueID-to-recipientAddress

• Behavior: Separate tracker for each unique recipient

• Use Case: Limit how much each user can receive

Per-From Address Tracker

• ID: 1-collection- -approvalId-uniqueID-from-senderAddress

• Behavior: Separate tracker for each unique sender

• Use Case: Limit how much each user can send

Per-InitiatedBy Address Tracker

• ID: 1-collection- -approvalId-uniqueID-initiatedBy-initiatorAddress

• Behavior: Separate tracker for each unique initiator

• Use Case: Limit how much each user can initiate

Detailed Example

Using the approval amounts defined above, when Alice initiates a transfer of x10 from Bob:

Two Trackers Get Incremented

#1) Overall Tracker

• ID: 1-collection- -approvalId-uniqueID-overall-

• Before: 0/1000

• After: 10/1000

• Behavior: Any subsequent transfers (from Charlie, etc.) will also increment this universal tracker

#2) Per-Initiator Tracker

• ID: 1-collection- -approvalId-uniqueID-initiatedBy-alice

• Before: 0/10

• After: 10/10 (fully used)

• Behavior: Only incremented when Alice initiates. Charlie's transfers use a separate tracker: 1-collection- -approvalId-uniqueID-initiatedBy-charlie

Amount Tracking with Balance Type

Trackers store amounts using the balance type structure. Above, we simplified it to just the amount.

{
    "amounts": [
        {
            "amount": 10n,
            "tokenIds": [{ "start": 1n, "end": 1n }],
            "ownershipTimes": [{ "start": 1n, "end": 100000000000n }]
        }
    ]
}

What Gets Incremented:

• Amount: The total quantity transferred

• Token IDs: Specific token IDs that were transferred

• Ownership Times: The ownership time ranges that were transferred

Unlimited Trackers (No Increment)

Since "to" and "from" trackers are set to "0" (unlimited), no tracking occurs for these types.

Tracker Behavior

• As-Needed: Only increment trackers when necessary (unlimited = no tracking)

• Separate Counts: Each tracker type maintains independent tallies

• Address Scoped: Per-address trackers create unique counters per address

• Balance Tracking: Increments for specific token IDs and ownership times transferred

Resets and ID Changes

Changing Tracker ID

When you update amountTrackerId from "uniqueID" to "uniqueID2":

1-collection- -approvalId-uniqueID-initiatedBy-alice
↓
1-collection- -approvalId-uniqueID2-initiatedBy-alice

Result: All tracker IDs change, so all tallies start from scratch.

Reusing Old IDs

If you later change back to "uniqueID", the starting point will be the previous tally:

• Alice's initiatedBy tracker: 10/10 used (not 0/10)

Important: Never reuse tracker IDs unless you want to continue from the previous state. They are increment-only.