Typescript SDK

[rhlsthrm]

Purpose

The purpose of the Amarok Typescript SDK is to facilitate front end integrations. The front end developer should not know anything about smart contract addresses, ABIs, subgraphs, or other implementation details.

Integrations that will use this are:

• Bridge UI
• Bridge Aggregators
• Dapps that want simple bridge + calldata functionality without needing any other contracts.

Functions

The SDK needs to contain the following functions to be useful:

• getChainsAndAssets: Provides all the chains and assets that we support (where do we get this info?).
• routeStatus: Provides status for a route, including if it's supported, liquidity available, etc. We can use this to signal if routes are not working/shut down for any reason. Unclear if subgraph sync status is required here but if so it can be included here.
• estimateFee: Estimates all fees including router fees and gas fees.
• checkApproval: Get status of token approval for Connext.sol contract.
• xcall: Initiates cross-domain transfers.
• getTransferStatus: Gets transfer status for a specific transfer.
• getPendingTransfers: Get transfers in progress for a user.
• getTransfers: Get historical transfers for a user.

The SDK needs to be aware of environments such as staging/prod, and testnet/mainnet.

[pjenviri]

Most of the functions listed above are similar to our thought. With Amarok, several steps of transfer will be eliminated. It will be easier for us as developers to call less complex functions while still being able to build cleaner apps on top of the protocol.

Below are the lists of functions being used in connextscan and the connext bridge:
connextscan

- fulfillTransfer
- cancel
- querySubgraph
- getSubgraphSyncStatus
- getRouterStatus

connext bridge

- getTransferQuote
- getEstimateReceiverAmount
- prepareTransfer
- getActiveTransactions
- fulfillTransfer
- cancel
- querySubgraph
- getSubgraphSyncStatus
- getRouterStatus

Amarok SDK (please correct me if I misunderstand anything)
(to confirm)

• Will the functions prepareTransfer and fullfillTransfer be changed to only xcall? If so, the fulfill functionality will not be needed on the explorer too. — this will be great for UX.
• No more cancel functionality in Amarok?
• Will the system have to check the subgraph sync status (for both src. & dest. chain) before initializing each bridging transfer? If so, the getSubgraphSyncStatus function is required.
• Will the current querySubgraph be changed to getTransferStatus? If yes, we think that keeping another querySubgraph function would be a good idea. This will be useful if we need to query any other information in the future.
• Will the getTransferStatus use the transferID (an output from xcall) as the key to query information?

Function to check the Fee estimation

• Having only estimateFee to get fee estimation with all provided details is a great idea.
• By the way, how about the getTransferQuote? Will it be a separate function?
• Is it possible to include getTransferQuote + getEstimateReceiverAmount in to the estimateFee? We think it will be easier for devs to get all the needed info by calling one request, and it will be less confusing.

Function to check the Active Transactions for each user
In Amarok, we understand that the Active Txs can be eliminated because users don’t need to sign. So they can check their transfer statuses directly on the explorer. What do you think about this?
Update: I just saw there’s the getActiveTransfers function listed. That’s nice to have.

Function to check the Max Transfer Size & assetBalance
Is this functionality still required on the bridge UI? (I think, yes.)
Currently, we check it from the assetBalance and routerStatus. Not sure that, in Amarok, this would check from the shared pool (not a particular router) or not. By the way, it would be good to include this function in the SDK. If yes, the function getRouterStatus would still be required (maybe change the name to getPoolStatus or other, IDK).

[rhlsthrm]

Will the functions prepareTransfer and fullfillTransfer be changed to only xcall? If so, the fulfill functionality will not be needed on the explorer too. — this will be great for UX.

Correct!

No more cancel functionality in Amarok?

Also correct. The mechanism falls back to the Nomad delay so the funds will always arrive eventually.

Will the system have to check the subgraph sync status (for both src. & dest. chain) before initializing each bridging transfer? If so, the getSubgraphSyncStatus function is required.

The goal here is to completely abstract the need for you to query subgraphs. Part of this will be by using the backend to serve the transfer data. However this brings up another good point, we should have functions that can query route status to signal if routes need to be shut down for some reason.

Will the getTransferStatus use the transferID (an output from xcall) as the key to query information?

Yes.

By the way, how about the getTransferQuote? Will it be a separate function?

No more need to get a quote. User can simply send funds and they will always arrive.

In Amarok, we understand that the Active Txs can be eliminated because users don’t need to sign. So they can check their transfer statuses directly on the explorer. What do you think about this?

Right, it just seems like a nice-to-have to have the user be able to see their in-flight transfers, i.e. if they refresh.

Is this functionality still required on the bridge UI? (I think, yes.)

Correct, will add this!

[maxklenk]

The functions sound great, but without knowing what parameters are required and how the response data might look like I can mainly tell you what I would wish for:

• routeStatus: Provides status for a route, including if it's supported, liquidity available, etc. We can use this to signal if routes are not working/shut down for any reason. Unclear if subgraph sync status is required here but if so it can be included here.

This is great, can the function be called to discover all available routes/assets or does it require parameters to get information about a specific route?

• estimateFee: Estimates all fees including router fees and gas fees.

A similar interface as in nxtp to be able to pass know gas usage of contract calls would be good

• checkApproval: Get status of token approval for Connext.sol contract.

Is there a way to access the contract address as well? Because after checking the allowance the integration has to set it.

• xcall: Initiates cross-domain transfers.

Will the execution of the transaction happen in the sdk or does it return a ethers.PopulatedTransaction which can then be handled by integrator? We would favor the second, to be able to set gasPrice, handle replaced transactions and so on.

• getTransferStatus: Gets transfer status for a specific transfer.

It would be good if the function would handle transactionIds and transactionHashes, similar to the search on connextscan

• getActiveTransfers: Get transfers in progress for a user.

Would be great to pass the users address

• getTransfers: Get historical transfers for a user.

Would be great to pass the users address

Will the sdk also provide functionality needed to increase the gas for the destination chain calls?

[rhlsthrm]

The functions sound great, but without knowing what parameters are required and how the response data might look like I can mainly tell you what I would wish for:

Will get the params in as the next step!

This is great, can the function be called to discover all available routes/assets or does it require parameters to get information about a specific route?

We should have a separate function to discover all available chains/assets. This is supposed to be for a specific combo of chains/assets. I will add another method.

A similar interface as in nxtp to be able to pass know gas usage of contract calls would be good

Absolutely this is necessary!

Is there a way to access the contract address as well? Because after checking the allowance the integration has to set it.

Would you want this exposed by contract address or should we include another function called approve?

Will the execution of the transaction happen in the sdk or does it return a ethers.PopulatedTransaction which can then be handled by integrator? We would favor the second, to be able to set gasPrice, handle replaced transactions and so on.

Agreed, we will likely ship both versions as we did before, a "BaseSDK" and an SDK which you pass in the provider to.

It would be good if the function would handle transactionIds and transactionHashes, similar to the search on connextscan

This is a great idea!

Will the sdk also provide functionality needed to increase the gas for the destination chain calls?

Not sure what you mean by this. Why would you want to increase the gas for destination calls? The calls should already be sent with enough gas to execute, and relayers handle the bumping.

[cryptostaker2021]

SDK functions looks great.

Few points:

1. One problem we face with current SDK is subgraph polling. It makes many network calls. is it possible to add a function/logic, which checks if there is on-going transaction than do more frequent polling and if there is no ongoing transaction then polling interval will be bigger.
   Also, client should be able to configure these values.

2. Cancellation/Expiry: This new version will have cancellation flow? If yes, can we have a method to check if a transaction can be cancelled at given point of time, so that client doesn't need to write cancellation condition logic.

3. Gas price/ fee: will it be possible to control at what gas price router submits transaction on target chain? This will impact the overall fee. For some use cases like cross chain staking, these are not time critical transactions. Users can wait for gas prices to drop, specially in case when target chain is Ethereum mainnet. 😸

[rhlsthrm]

One problem we face with current SDK is subgraph polling. It makes many network calls. is it possible to add a function/logic, which checks if there is on-going transaction than do more frequent polling and if there is no ongoing transaction then polling interval will be bigger.

There will be no more subgraph polling! This is not needed in the new version.

Cancellation/Expiry: This new version will have cancellation flow? If yes, can we have a method to check if a transaction can be cancelled at given point of time, so that client doesn't need to write cancellation condition logic.

No more cancellations at all! New flow will always push funds to the user, either through routers instantly or in 30 minutes with Nomad.

Gas price/ fee: will it be possible to control at what gas price router submits transaction on target chain? This will impact the overall fee. For some use cases like cross chain staking, these are not time critical transactions. Users can wait for gas prices to drop, specially in case when target chain is Ethereum mainnet. 😸

The user will control the relayer fee so they can determine how much to put up. We can add some better control around determining the relayer fee to use! CC @bld84 around submitting txs slower and cheaper, is that possible through Gelato?

[LayneHaber]

getChainsAndAssets: Provides all the chains and assets that we support (where do we get this info?).

This should be available from the subgraph -- you can monitor assets via AssetAdded events and supported chains from the ReplicaEnrolled / ReplicaUnenrolled events

estimateFee: Estimates all fees including router fees and gas fees.

How flexible do you envision this being? i.e. if the user needs more MATIC but has enough USDC, should this be able to get the proper amount of USDC to swap into MATIC? How would that information be conveyed? If you envision this being extremely flexible, then we may need a getEstimatedFee or something function that is able to get the fee in the right assets

getActiveTransfers: Get transfers in progress for a user.

Can we name this getPendingTransfers instead? there's no second step and active implies that there's something to resolve

[rhlsthrm]

This should be available from the subgraph -- you can monitor assets via AssetAdded events and supported chains from the ReplicaEnrolled / ReplicaUnenrolled events

We don't have the Replica events in a subgraph yet, we should add them to our subgraph: #1010

How flexible do you envision this being? i.e. if the user needs more MATIC but has enough USDC, should this be able to get the proper amount of USDC to swap into MATIC? How would that information be conveyed? If you envision this being extremely flexible, then we may need a getEstimatedFee or something function that is able to get the fee in the right assets

Once we have finalization around gas fees, we can do this. The idea is this would get all estimated fees. What would be the difference between getEstimatedFee and estimateFees? These are the same thing.

Can we name this getPendingTransfers instead? there's no second step and active implies that there's something to resolve

Sure!