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 amount using the BigInt type
  "tokenIds": [{ 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,
    tokenIds: [{ 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,
    tokenIds: [{ 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 balances. With the addBalance and subtractBalance functions, you can effortlessly update and maintain 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 Token ID and Time

1. Get Balance for a Specific ID and Time

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

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

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

2. Get Balances for a Specific Token ID

To get all balances associated with a specific token ID:

const tokenIdToLookup = 4n;
const balances = balances.getBalancesForId(tokenIdToLookup);

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

3. Get Balances for a Specific Time

If you need to retrieve all 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 token IDs and a range of times, let's create a tutorial snippet for it:

1. Get Balances for Specific Ranges of Token IDs and Times

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

// Define the range of token 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 token ID ranges and time ranges.

Conclusion

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