fix(rpc): support contract addresses in requestAirdrop()

[joaquinsoza]

Summary
Adds support for funding contract addresses (C...) via requestAirdrop().

Changes

• Detect contract addresses using StrKey.isValidContract()
• Return ContractFundingResult for contracts instead of parsing account metadata
• Add Api.ContractFundingResult type
• Add unit tests

Fixes #1313

[Ryang-21]

I am hesitant to have requestAirdrop return two different types. Since this will be a breaking change my thought was to just return the Api.GetTransactionResponse for both types Address Thoughts @Shaptic?

[joaquinsoza]

I am hesitant to have requestAirdrop return two different types. Since this will be a breaking change my thought was to just return the Api.GetTransactionResponse for both types Address Thoughts @Shaptic?

Yeah, that makes sense! It could look something like this:

public async requestAirdrop(
  address: string | Pick<Account, "accountId">,
  friendbotUrl?: string,
): Promise<Api.GetTransactionResponse> {
  const account = typeof address === "string" ? address : address.accountId();

  friendbotUrl = friendbotUrl || (await this.getNetwork()).friendbotUrl;
  if (!friendbotUrl) {
    throw new Error("No friendbot URL configured for current network");
  }

  const response = await this.httpClient.post<FriendbotApi.Response>(
    `${friendbotUrl}?addr=${encodeURIComponent(account)}`,
  );

  // Return full transaction response for both G... and C... addresses
  return this.getTransaction(response.data.hash);
}

Usage would then be:

const tx = await server.requestAirdrop(address);
if (tx.status === Api.GetTransactionStatus.SUCCESS) {
  console.log("Funded:", tx.txHash);
}

// If user needs Account object for G... addresses:
const account = await server.getAccount(address);

This simplifies the implementation and gives users more flexibility with the full transaction details. Happy to update the PR if you'd like to go this direction.

[Ryang-21]

Hey @joaquinsoza sorry for the delay I've thought about it some more and think it would be better to go the route of keeping requestAirdrop the same and mark it as depreciated. We can then create a new function on the rpc server called fundAddress and implement the solution you had suggested.

Would you be interested in updating the PR to reflect this direction? If not, I’m happy to take it over and implement the changes myself.

[Shaptic]

Yeah I’m inclined to agree with @Ryang-21 here: we don’t want to break every existing requestAirdrop user, even at a major version boundary: that’s too disruptive I think. A new method makes more sense that returns a single type, though then it becomes a challenge to create an Account object from that result, so we’d need to add that as well to minimize the impact on users.

[Copilot]

Pull request overview

This pull request adds a new fundAddress() method to support funding both Stellar account (G...) and contract (C...) addresses via the Friendbot faucet. The existing requestAirdrop() method is deprecated in favor of this new method.

Changes:

• Added new fundAddress() method that returns transaction response instead of Account object
• Deprecated requestAirdrop() with a note directing users to the new method
• Added comprehensive test suite for the new method covering various scenarios

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
src/rpc/server.ts	Added fundAddress() method and deprecated requestAirdrop()
test/unit/server/soroban/request_airdrop.test.ts	Added test suite for fundAddress() with tests for accounts, contracts, custom URLs, and error cases

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[joaquinsoza]

Thanks for the feedback @Ryang-21 @Shaptic! I've updated the PR with the suggested approach:

Changes:

• Kept requestAirdrop() unchanged and marked it as @deprecated
• Added new fundAddress() method that:
  • Supports both G... (account) and C... (contract) addresses
  • Returns Api.GetSuccessfulTransactionResponse (single type)
  • Calls getTransaction() to get the full transaction details

Usage:

// Fund any address (account or contract)                                                       
const tx = await server.fundAddress(address);                                                   
console.log("Funded! Hash:", tx.txHash);                                                        
                                                                                                
// If you need an Account object for G... addresses:                                            
const account = await server.getAccount(address);                                               

Regarding creating an Account object from the result - I documented that users can call
server.getAccount() after funding. Let me know if you'd prefer a convenience method like
fundAndCreateAccount() that combines both steps for account addresses, or if the current
approach is sufficient.

[Ryang-21]

Lgtm appreciate the contribution!