“Add Token” via freighter-api

[CassioMG]

Related issue: #1646

This PR adds the addToken functionality via freighter-api, it uses the existing signTransaction and signMessage APIs as inspiration.

The addToken API takes both a contractId and a networkPassphrase as input which Freighter will use to load the token details (e.g. symbol, name, decimals and balance) for the user.

Freighter will then show these token details along with any applicable warnings. The user will need to approve it in order for the token to be added.

This PR extracts the token lookup and change trustline functionalities into the useTokenLookup and useChangeTrustline hooks respectively so we can reuse the "add token" logic in both our API and manual approaches.

Adding a custom token with the addToken API

custom-token.mov

Adding a SAC token with the addToken API

sac-token.mov

Asset lists and Blockaid warning messages

Documentation update

[aristidesstaffieri]

is there any reason to not use the balance from the backend in this case? We only want to use the rpc locally in the case of a custom network in general.

[piyalbasu]

Second this. We should use the backend to fetch balances and token details (unless we're on a custom network).

Also, using buildSorobanServer with networkDetails.sorobanRpcUrl will not work on mainnet because our Soroban RPC url for Mainnet is on a private kube cluster that only our backend can reach. You'll see that if you hit this method on Mainnet that the call will fail

[CassioMG]

@aristidesstaffieri @piyalbasu Thanks for raising this!

So I ended up adding this RPC fetch because the backend request was not returning the balance. It's currently returning an object like this:

{
  name: string;
  decimals: number;
  symbol: string;
}

I'll take a look at the backend code to see what we could do there.

[CassioMG]

PR opened here: stellar/freighter-backend#204

[aristidesstaffieri]

Curious why this says "Simulated Balance Changes"?

Isn't adding a token only bringing into your Freighter balances? I don't think this changes a balance or simulates a balance change.

[CassioMG]

Good point, I was simply following the Designs here. Looks like @sdfcharles tried using the same wording from other screens, but thinking about this now I think something like "Balance Info" would probably make more sense here.

What do you think?

[aristidesstaffieri]

Yeah something like that seems more appropriate to me but maybe we could have @sdfcharles weigh in.

[CassioMG]

156cc27

[piyalbasu]

I'm still taking a look at this (sorry for the delay!). But could you please add documentation for this new method in docs/docs/guide/usingFreighterWebApp.md? It'd be great to have this outlined next to all the other methods.

[CassioMG]

I'm still taking a look at this (sorry for the delay!). But could you please add documentation for this new method in docs/docs/guide/usingFreighterWebApp.md? It'd be great to have this outlined next to all the other methods.

@piyalbasu great catch, I'll add it

[CassioMG]

@piyalbasu I've added the missing documentation for addToken and I noticed it was also missing for the getNetworkDetails api so I went ahead and added both (here and here). Let me know what you think: