Feature/api integration skill#2702
Feature/api integration skill#2702leofelix077 wants to merge 2 commits intofeature/troubleshooting-guidefrom
Conversation
leofelix077
added
wip
leofelix077
changed the base branch from
master
to
feature/troubleshooting-guide
There was a problem hiding this comment.
Pull request overview
Adds a new documentation “skill” (freighter-api-integration) describing best practices for dApps integrating with the Freighter wallet via @stellar/freighter-api or via @creit.tech/stellar-wallets-kit.
Changes:
- Introduces the
freighter-api-integrationskill entrypoint with an API/reference index. - Adds reference docs for connection flow, signing, network/account change handling, and error handling.
- Adds guidance for integrating Freighter through stellar-wallets-kit and common anti-patterns.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/skills/freighter-api-integration/SKILL.md | Defines the skill metadata and provides a high-level API surface + reference map. |
| docs/skills/freighter-api-integration/references/connection-flow.md | Documents recommended connect/allow/address flow using freighter-api methods. |
| docs/skills/freighter-api-integration/references/signing.md | Documents signTransaction, signMessage, and signAuthEntry behaviors and pitfalls. |
| docs/skills/freighter-api-integration/references/network-and-events.md | Documents polling via WatchWalletChanges and choosing getNetwork* methods. |
| docs/skills/freighter-api-integration/references/error-handling.md | Explains the { ...data, error? } result shape, SSR behavior, and user-facing messaging. |
| docs/skills/freighter-api-integration/references/anti-patterns.md | Provides “don’t/do” examples for common integration mistakes. |
| docs/skills/freighter-api-integration/references/stellar-wallets-kit.md | Explains when/how to use SWK for multi-wallet support and how it differs from direct SDK usage. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| if (error) throw new Error(error.message); | ||
| const signedTx = TransactionBuilder.fromXDR(signedTxXdr, networkPassphrase); | ||
| ``` |
There was a problem hiding this comment.
In this example, networkPassphrase is not defined when calling TransactionBuilder.fromXDR(...), so the snippet won’t compile and it’s unclear which passphrase should be used. Consider either reusing the same passphrase you passed to signTransaction (e.g., store it in a variable) or showing the recommended pattern of reading it from getNetwork() before signing and parsing.
| ```ts | ||
| const { signedAuthEntry, signerAddress, error } = await signAuthEntry( | ||
| authEntry.toXDR("base64"), | ||
| { networkPassphrase: Networks.PUBLIC, address: signerAddress }, |
There was a problem hiding this comment.
This signAuthEntry example passes address: signerAddress, but signerAddress is only available after the call resolves. The address option should be an already-known expected address (or omitted), otherwise the snippet is self-referential and confusing.
| { networkPassphrase: Networks.PUBLIC, address: signerAddress }, | |
| { networkPassphrase: Networks.PUBLIC }, |
| import { | ||
| isConnected, | ||
| isAllowed, | ||
| setAllowed, |
There was a problem hiding this comment.
The sample imports setAllowed but never uses it in connect(). To keep the example copy/paste-friendly, either remove setAllowed from the import list or add a branch demonstrating the setAllowed() + getAddress() flow.
| setAllowed, |
| ```ts | ||
| const { signedTxXdr, signerAddress } = await kit.signTransaction(tx.toXDR(), { | ||
| address: account, | ||
| networkPassphrase: WalletNetwork.PUBLIC, |
There was a problem hiding this comment.
In the SWK signing snippet, the option is labeled networkPassphrase but the value provided is WalletNetwork.PUBLIC (a network identifier). This is internally inconsistent and may mislead readers about what SWK expects here; please align the prose and example with the actual SWK API (either pass a real network passphrase string, or rename the option/description to indicate it takes a WalletNetwork).
| networkPassphrase: WalletNetwork.PUBLIC, | |
| networkPassphrase: "Public Global Stellar Network ; September 2015", |
| const { signedTxXdr, signerAddress, error } = await signTransaction( | ||
| tx.toXDR(), | ||
| { | ||
| networkPassphrase: Networks.PUBLIC, // or Networks.TESTNET |
There was a problem hiding this comment.
This section later recommends reading networkPassphrase from getNetwork() right before signing, but the primary signTransaction example hardcodes Networks.PUBLIC. Consider updating the example to follow the recommended practice to avoid readers copying the hardcoded passphrase pattern.
| const { signedTxXdr, signerAddress, error } = await signTransaction( | |
| tx.toXDR(), | |
| { | |
| networkPassphrase: Networks.PUBLIC, // or Networks.TESTNET | |
| const { networkPassphrase, error: networkError } = await getNetwork(); | |
| if (networkError) throw new Error(networkError.message); | |
| const { signedTxXdr, signerAddress, error } = await signTransaction( | |
| tx.toXDR(), | |
| { | |
| networkPassphrase, |
No description provided.