Add abstractions for converting ScVals to native types.

[Shaptic]

Is your feature request related to a problem? Please describe.
Given an arbitrary ScVal type, converting it into a form natively usable from your chosen language is difficult and error prone.

Describe the solution you'd like
Easy conversion methods from ScVals to native types.

Here is the list of types and conversations:

• scvBool ➡️ boolean
• scvVoid ➡️ null
• scvU32 ➡️ number
• scvI32 ➡️ number
• scvU64 ➡️ bigint
• scvI64 ➡️ bigint
• scvTimepoint ➡️ bigint
• scvDuration ➡️ bigint
• scvU128 ➡️ bigint
• scvI128 ➡️ bigint
• scvU256 ➡️ bigint
• scvI256 ➡️ bigint
• scvBytes ➡️ Buffer (or should it be Uint8Array?)
• scvString ➡️ string
• scvVec ➡️ Array<T>
• scvMap ➡️ Map<ScVal, any>, where each ScVal is converted to its native type if possible
• scvAddress ➡️ Address

Some conversions are unclear and the value of an abstraction for them is a little unclear:

• scvSymbol
• scvContractExecutable
• scvLedgerKeyContractExecutable
• scvLedgerKeyNonce
• scvStatus

Describe alternatives you've considered
Suffering.

Additional context
Original feature request from @piyalbasu here: stellar/js-soroban-client#43.
Discord discussion here: https://discord.com/channels/897514728459468821/1111621289900253245.

[leighmcculloch]

• scvU64 ➡️ ScInt
• scvI64 ➡️ ScInt
• scvTimepoint ➡️ bigint
• scvDuration ➡️ bigint
• scvU128 ➡️ ScInt
• scvI128 ➡️ ScInt
• scvU256 ➡️ ScInt
• scvI256 ➡️ ScInt

What's the win with ScInt for some greater than 53-bit int's when bigint is available?

[Shaptic]

@leighmcculloch please refer to #620: it allows easy conversion between number|string|bigint ↔️ ScVals.

I suppose having it go to bigint would be fine, too; then users can new ScInt(...) it if they need the abstraction. Or they can .toBigInt() on the ScInt instance in the same way.

[leighmcculloch]

That's fine too, however to your point in the doc that linked to this issue, there's so much confusion created by the exposure of non-native types like xdr types, so anything we can do to make them fade away rather than use them or types like them for conversions will probably improve the developer experience. At least to the extent we can do so without compromising on capability.

[Shaptic]

Yep, you make a good point! bigint is a better "landing pad" for intuition, then they can use the other abstractions as needed

[willemneal]

One thing to note. Scvmap could be a rust struct, which would be better represented as a js object (TS interface). I had initially gone with Map, but it's a much worse DevX experience than just accessing a field. So perhaps the conversion interface should also allow passing the corresponding ScTypeDef.

As for the bytes I vote Uint8Array as Buffer is not as cross platform.

[Shaptic]

I moved away from Buffer in 10a69fe, but the migration to do custom type specification definitely needs more thought and work, so I'm going to merge #630 as is to have a decent starting point.

Can you expand a bit on the API and input/output you might like to see, so I can get a better sense of what you're looking for?

[willemneal]

It would be similar to the CLI:

https://github.com/stellar/soroban-tools/blob/d16a84c2bbceccec67c3fa06a6d8f6f294a055bc/cmd/crates/soroban-spec-tools/src/lib.rs#L486

The tricky part is figuring out the corresponding the ScTypeDef. This could be done by the bindings code.

For example adding it here:

https://github.com/stellar/soroban-tools/blob/d16a84c2bbceccec67c3fa06a6d8f6f294a055bc/cmd/crates/soroban-spec-typescript/fixtures/ts/src/index.ts#L235

[Shaptic]

I'm marking this as closed by #630 for tracking purposes, but opening a new issue for the remaining work!