sync: main to staging

docs/general/multi-chain-realtime-transaction-and-packet-tracking.mdx

@@ -59,6 +59,7 @@ The `transfer_sequence` array consists of `TransferEvent` objects, which give de
 * `AxelarTransferInfo`
 * `HyperlaneTransferInfo`
 * `GoFastTransferInfo`
+* `StargateTransferInfo`
 
 Each one contains slightly different data and statuses corresponding to the details of their bridge, but they all contain some standard info: 
 * `from_chain_id`
@@ -174,8 +175,8 @@ When one of the transfers is a `GoFastTransfer`, the `transfer_sequence` array w
 
 Below are detailed explanations of the different fields and their purposes:
 
-* `fromChainID`: The chain ID where the transfer originates (source chain).
-* `toChainID`: The chain ID where the assets are being sent (destination chain).
+* `from_chain_id`: The chain ID where the transfer originates (source chain).
+* `to_chain_id`: The chain ID where the assets are being sent (destination chain).
 * `state`: Indicates the current status of the transfer. Possible values are:
   * `GO_FAST_TRANSFER_UNKNOWN`: An unknown error has occurred.
   * `GO_FAST_TRANSFER_SENT`: The user's intent has been successfully submitted on the source chain.
@@ -184,14 +185,36 @@ Below are detailed explanations of the different fields and their purposes:
   * `GO_FAST_TRANSFER_FILLED`: The transfer was successfully fulfilled on the destination chain.
   * `GO_FAST_TRANSFER_REFUNDED`: The user's assets have been refunded on the source chain.
 * `txs`: Contains transaction details related to the GoFast transfer:
-  * `orderSubmittedTx`: The transaction where the user called initiateIntent on the source chain.
-  * `orderFilledTx`: The transaction where the solver called fulfill on the destination chain.
-  * `orderRefundedTx`: The transaction where the user received a refund on the source chain, if applicable.
-  * `orderTimeoutTx`: The transaction indicating a timeout occurred in the transfer process.
+  * `order_submitted_tx`: The transaction where the user called initiateIntent on the source chain.
+  * `order_filled_tx`: The transaction where the solver called fulfill on the destination chain.
+  * `order_refunded_tx`: The transaction where the user received a refund on the source chain, if applicable.
+  * `order_timeout_tx`: The transaction indicating a timeout occurred in the transfer process.
 
 
 When tracking a Go Fast transfer, you can use the `GoFastTransferInfo` to monitor the progress and status of your asset transfer between chains. For instance, if the state is `GO_FAST_TRANSFER_FILLED`, you know that the transfer was successful and your assets should be available on the destination chain. If the state is `GO_FAST_TRANSFER_TIMEOUT`, you can check the `orderTimeoutTx` for details on the timeout event.
 
+### Stargate Transfer Data
+
+When one of the transfers is a `StargateTransfer`, the `transfer_sequence` array will include a `stargate_transfer` (`StargateTransferInfo`). This provides detailed information about a cross-chain asset transfer powered by Stargate, a popular cross-chain bridging protocol.
+
+Below are detailed explanations of the fields and their purposes:
+
+* `from_chain_id`: The chain ID where the transfer originates (source chain).
+* `to_chain_id`: The chain ID where the assets are being sent (destination chain).
+
+* `state`: Indicates the current status of the Stargate transfer. Possible values are:
+  * `STARGATE_TRANSFER_UNKNOWN`: An unknown error has occurred or the state cannot be determined.
+  * `STARGATE_TRANSFER_SENT`: The transfer has been successfully initiated on the source chain (i.e., the assets have left the source chain and are in transit).
+  * `STARGATE_TRANSFER_RECEIVED`: The transfer has been successfully completed on the destination chain (i.e., the assets are now available at the recipient address on the destination chain).
+  * `STARGATE_TRANSFER_FAILED`: The transfer encountered an error during bridging and did not complete as intended.
+
+* `txs`: Contains transaction details related to the Stargate transfer. 
+  * `send_tx`: The transaction on the source chain that initiated the Stargate transfer. 
+  * `receive_tx`: The transaction on the destination chain where the assets were received.
+  * `error_tx`: A transaction (if any) related to the failure of the transfer. 
+
+When monitoring a Stargate transfer, you can use `StargateTransferInfo` to confirm that your assets have safely bridged between chains or identify if and where a problem has occurred. 
+
 <Info>
 The Go Fast Protocol involves interactions with solvers who fulfill transfer intents. The additional transaction fields help provide transparency and traceability throughout the transfer process, ensuring users can track each step and identify any issues that may arise.
 </Info>

docs/widget/configuration.mdx

@@ -187,53 +187,79 @@ chainIdsToAffiliates: {
 }
 ```
 
-## Coming Soon
-
-The following props are in development and will be available soon.
-
 ### `callbacks`
 
 Event handling functions.
 
 ```ts
-onWalletConnected?: ({ walletName: string, chainId: string, address?: string }) => void;
-onWalletDisconnected?: ({ chainType?: string }) => void;
-onTransactionBroadcasted?: ({ txHash: string, chainId: string, explorerLink: string }) => void;
-onTransactionComplete?: ({ txHash: string, chainId: string, explorerLink: string }) => void;
-onTransactionFailed?: ({ error: string }) => void;
-onValidateGasBalance?: (value: {
-    chainID?: string;
-    txIndex?: number;
-    status: "success" | "error" | "pending" | "completed"
-  }) => Promise<void>;
+onWalletConnected?: (params: {
+  walletName?: string;
+  chainIdToAddressMap: Record<string, string>;
+  address?: string;
+}) => void;
+
+onWalletDisconnected?: (params: {
+  walletName?: string;
+  chainType?: string;
+}) => void;
+
+onTransactionBroadcasted?: (params: {
+  txHash: string;
+  chainId: string;
+  explorerLink?: string;
+}) => void;
+onTransactionComplete?: (params: {
+  txHash: string;
+  chainId: string;
+  explorerLink?: string;
+}) => void;
+onTransactionFailed?: (params: { error: Error }) => void;
 ```
 
 - `onWalletConnected`: Called when a wallet is connected.
 - `onWalletDisconnected`: Called when a wallet is disconnected.
 - `onTransactionBroadcasted`: Called when a transaction is broadcasted. This is called multiple times for multi-transaction routes. 
 - `onTransactionComplete`: Triggered when a transaction is completed.
 - `onTransactionFailed`: Triggered when a transaction fails.
-- `onValidateGasBalance`: Triggered when validating gas balance.
 
-### `connectedWallet`
+### `connectedAddresses` & `signers`
+
+If your application has already connected to a user's wallet (e.g., via MetaMask for EVM networks, Phantom for Solana, or Keplr for Cosmos), you **must provide both** the `connectedAddresses` and corresponding signer functions in order to enable the widget’s injected wallet functionality.  
+See an implementation example [here](https://github.com/skip-mev/skip-go/tree/staging/examples/nextjs/src/app/injected/page.tsx).
 
-Inject your own wallet provider into the `Widget`. See an implementation example [here](https://github.com/skip-mev/skip-go/blob/3a7dcadde0eb0604c795b6a3bc857e6d2209b7a7/examples/nextjs/pages/inject-wallet.tsx#L73).
 `WalletClient` comes from the [`viem` package](https://viem.sh/docs/clients/wallet.html). `Adapter` comes from the [`@solana/wallet-adapter-base` package](https://solana.com/developers/cookbook/wallets/connect-wallet-react). And `OfflineSigner` comes from the [`@cosmjs` package](https://docs.keplr.app/api/cosmjs.html).
 
-```ts
-connectedWallet?: {
-  cosmos?: {
-    getAddress: (chainID: string) => Promise<string>;
-    getSigner: (chainID: string) => Promise<OfflineSigner>
-  };
-  evm?: {
-    getAddress: (chainID: string) => Promise<string>;
-    getSigner: (chainID: string) => Promise<WalletClient>;
-  };
-  svm?: {
-    getAddress: (chainID: string) => Promise<string>;
-    getSigner: () => Promise<Adapter>;
-  };
+- **Type:** `Record<ChainId, Address>`
+
+**Example:**
+```typescript
+const connectedAddresses: Record<string, string> = {
+  "1": "0x123...abc",          // Ethereum mainnet address
+  "cosmoshub-4": "cosmos1...", // Cosmos Hub address
+  "solana": "3n9...xyz",       // Solana address
+  // ... add more chain IDs and addresses as needed
 };
 ```
 
+### Signer Functions
+
+Each signer function below must be implemented to fully leverage the injected wallet capabilities:
+
+- **`getCosmosSigner(): Promise<OfflineSigner>`**  
+  Returns a Cosmos-compatible signer.
+
+- **`getEVMSigner(): Promise<WalletClient>`**  
+  Returns an EVM-compatible signer (e.g., from `viem`).
+
+- **`getSVMSigner(): Promise<PhantomWalletAdapter>`**  
+  Returns a Solana-compatible signer, such as a `PhantomWalletAdapter`.
+
+**Complete Example for injected wallet functionality:**
+```jsx
+<Widget
+  connectedAddresses={connectedAddresses}
+  getCosmosSigner={getCosmosSigner}
+  getEVMSigner={getEVMSigner}
+  getSVMSigner={getSVMSigner}
+/>
+```

docs/widget/connected-wallet.mdx

@@ -0,0 +1,43 @@
+---
+title: 'Connected Wallet'
+
+---
+
+## Overview
+
+If your application has already connected to a user's wallet (e.g., via MetaMask for EVM networks, Phantom for Solana, or Keplr for Cosmos), you can provide this information directly to the Widget. By doing so, the Widget will:
+
+- Display and query balances for the user's already-connected wallet addresses for supported chains.
+- Use the signer functions you provide to facilitate transactions, token swaps, or any operation that requires the user's signature.
+
+This eliminates the need for the user to perform a separate connection flow within the widget itself, improving their overall experience and reducing friction.
+
+<Info>
+See a full code example [here](https://github.com/skip-mev/skip-go/tree/staging/examples/nextjs/src/app/injected/page.tsx).
+</Info>
+
+## Key Props and Concepts
+
+### `connectedAddresses`
+
+The `connectedAddresses` prop is a map from chain IDs to addresses. This map tells the widget which addresses are currently connected and should be used for transactions.
+
+- **Type:** `Record<ChainId, Address>`
+- **Example:** 
+  ```typescript
+  const accountMap: Record<string, string> = {
+    "1": "0x123...abc",          // Ethereum mainnet address
+    "solana": "3n9...xyz",       // Solana address
+    "cosmoshub-4": "cosmos1...", // Cosmos Hub address
+    ...
+  };
+
+### Signer Functions
+
+In addition to passing in `connectedAddresses`, you must also provide the widget with signer functions so it can sign and send transactions on behalf of the user. These functions vary by chain type and are provided as separate props:
+
+- `getCosmosSigner() => Promise<OfflineSigner>`
+- `getEVMSigner() => Promise<WalletClient>`
+- `getSVMSigner() => Promise<PhantomWalletAdapter>`
+
+Each of these functions should return a signer (or signer-like interface) that the widget can use to create and broadcast transactions.

examples/nextjs/CHANGELOG.md

@@ -1,5 +1,19 @@
 # nextjs
 
+## 0.1.28
+
+### Patch Changes
+
+- dacf973: fix example default route and client asset search
+- Updated dependencies [dacf973]
+- Updated dependencies [dacf973]
+- Updated dependencies [dacf973]
+- Updated dependencies [dacf973]
+- Updated dependencies [dacf973]
+- Updated dependencies [dacf973]
+- Updated dependencies [dacf973]
+  - @skip-go/[email protected]
+
 ## 0.1.27
 
 ### Patch Changes

examples/nextjs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nextjs",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "private": true,
   "scripts": {
     "dev": "next dev",