Add Server.getSACBalance for fetching built-in token balance entries

[Shaptic]

What

This introduces a new method to the server:

function getSACBalance(
  contractId: string,
  token: Asset,
  networkPassphrase?: string
): Promise<Api.BalanceResponse>

which returns the following schema:

export interface ContractBalanceResponse {
  latestLedger: number;
  // present only on success, otherwise request malformed or no balance
  balance?: {
    amount: string;
    authorized: boolean;
    clawback: boolean;

    lastModifiedLedgerSeq?: number;
    liveUntilLedgerSeq?: number;
  };
}

Why?

It allows developers to fetch how much of a particular SAC is stored within a contract. For example, you may have a liquidity pool contract and want to see its balance of USDC without actually invoking a function. You can achieve that by calling

const balanceEntry = await new rpc.Server("the rpc url").getSACBalance(
  "C...", // the LP contract
  new Asset("USDC", "G..." /* the issuer */),
  Networks.TESTNET, // or whatever network the contracts are built on
);

See #1003.

[github-actions]

Size Change: +32.6 kB (+0.27%)

Total Size: 12.2 MB

Filename	Size	Change
dist/stellar-sdk.js	6.84 MB	+21.1 kB (+0.31%)
dist/stellar-sdk.min.js	5.38 MB	+11.5 kB (+0.21%)

_{compressed-size-action}

[aristidesstaffieri]

@Shaptic Do you think there would ever be confusion about being able to use this for custom tokens also?
I see that having to pass in an Asset implies that it has to be a SAC but maybe calling it getSACBalance or something would make it extra clear?

[sreuland]

@Shaptic Do you think there would ever be confusion about being able to use this for custom tokens also? I see that having to pass in an Asset implies that it has to be a SAC but maybe calling it getSACBalance or something would make it extra clear?

👍 , ContractBalance could allow wider interpretation, since this is implicit to only built-in token contracts of network assets, docs use the SAC terminology in description of type of built-in token contract , for consistency here on fn and response could rename - /ContractBalance/SACBalance/

[Shaptic]

Great call on that @aristidesstaffieri and @sreuland; done in 8bc0e2d!

[aristidesstaffieri]

lgtm!

[sreuland]

great work!