Balances

Documentation Link: Here -> Balances

Tutorial: Using the TypeScript SDK for Balance Operations

1. Define the Balance

Here's how you create a balance using the provided Balance interface:

const userBalance = BalanceArray.From([{
  "amount": 5n, // example badge amount using the BigInt type
  "badgeIds": [{ start: 1n, end: 5n }],
  "ownershipTimes": [{ start: 1628770800000n, end: 1628857200000n }] // example timestamps using BigInt
}])

Note: The UintRange type is assumed to be an object with start and end properties of type bigint. Adjust as necessary based on the actual definition.

2. Add Balance

To add a balance to an array of existing balances:

const balanceToAdd = {
  amount: 3n,
  badgeIds: [{ start: 6n, end: 8n }],
  ownershipTimes: [{ start: 1628860800000n, end: 1628947200000n }]
};
userBalance.addBalances([balanceToAdd]);

This will add balanceToAdd to the list of existing balances.

3. Subtract Balance

To subtract a balance from an array of existing balances:

const balanceToRemove = {
  amount: 2n,
  badgeIds: [{ start: 2n, end: 3n }],
  ownershipTimes: [{ start: 1628784400000n, end: 1628870800000n }]
};
userBalance.subtractBalances([balanceToRemove], false) //second param is to allow underflow (negatives)

Conclusion

This SDK provides a clear and structured way to manage and operate on badge balances. With the addBalance and subtractBalance functions, you can effortlessly update and maintain badge balances in your application. Given the new functions you've shared, I'll provide a tutorial snippet for each of them.

Tutorial: Retrieving Balances Based on Badge ID and Time

1. Get Balance for a Specific ID and Time

If you need to retrieve the balance for a specific badge ID and a specific ownership time, you can use the getBalanceForIdAndTime function:

const badgeIdToLookup = 3n;
const timeToLookup = 1628784400000n;  // example timestamp using BigInt
const specificBalance = balances.getBalanceForIdAndTime(badgeIdToLookup, timeToLookup);

console.log(specificBalance); // This will show the balance for the specified badge ID and time, if found.

2. Get Balances for a Specific Badge ID

To get all balances associated with a specific badge ID:

const badgeIdToLookup = 4n;
const badgeBalances = balances.getBalancesForId(badgeIdToLookup);

console.log(badgeBalances); // This will display all the balances for the given badge ID.

3. Get Balances for a Specific Time

If you need to retrieve all badge balances for a specific ownership time:

const timeToLookup = 1628784400000n;
const timeSpecificBalances = balances.getBalancesForTime(timeToLookup);

console.log(timeSpecificBalances); // This will show all the balances that have the specified ownership time.

Alright, given the new function getBalancesForIds which retrieves balances for a range of badge IDs and a range of times, let's create a tutorial snippet for it:

4. Get Balances for Specific Ranges of Badge IDs and Times

If you need to retrieve balances for a range of badge IDs and a range of ownership times, you can utilize the getBalancesForIds function:

// Define the range of badge IDs and times you want to look up
const idRangesToLookup = [
    { start: 1n, end: 3n },
    { start: 5n, end: 7n }
];

const timeRangesToLookup = [
    { start: 1628770800000n, end: 1628857200000n },  // example timestamp range using BigInt
    { start: 1628943600000n, end: 1629030000000n }   // another timestamp range
];

// Retrieve the balances
const specificBalances = balances.getBalancesForIds(idRangesToLookup, timeRangesToLookup);
console.log(specificBalances); // This will show the balances that fall within the specified badge ID ranges and time ranges.

Conclusion

The provided functions in this SDK make it easy to retrieve specific badge balances based on different criteria, such as badge ID and ownership time. Utilize these functions to access and display relevant data as per your application's requirements.