Update AccountCreateTransaction docs: add key/alias methods and reflect deprecations

[jaycoolh]

Summary

The docs for creating accounts with the SDK need to be updated to include all relevant key/alias setters on AccountCreateTransaction, reflect the deprecation of setKey, and provide a concise explanation of when to use each method.

Context

• Current docs list setKey and setAlias in the methods table, and show setKeyWithAlias in the code snippet.
• The SDK exposes five related methods:
  • setKey (deprecated)
  • setAlias
  • setKeyWithAlias
  • setKeyWithoutAlias
  • setECDSAKeyWithAlias
• The Dev Playground currently uses setECDSAKeyWithAlias.

Relevant page: https://docs.hedera.com/hedera/sdks-and-apis/sdks/accounts-and-hbar/create-an-account

Discussion Highlights

".setKey is deprecated"

"They all work as expected..."

"Deprecated means it should be discouraged from use and will continue to work until it is removed from support. We should encourage non-deprecated fields in our docs."

"You cannot have .setAlias without .setKey. These 2 methods go hand in hand...."

"We can list that it is deprecated and what they should use instead."

"We also need a brief explainer... The goal is to help the user understand what each method does, which one is the recommended one for most, and which one they need for their use case."

Action Items

• Methods table: add entries for setKeyWithAlias, setKeyWithoutAlias, and setECDSAKeyWithAlias with clear descriptions and applicability (key type and behavior)
• Mark setKey as deprecated in the methods table with guidance on replacements (prefer combined methods; see recommendation decision in separate issue)
• Clarify that setAlias requires a key to be set, and discourage the separate setKey + setAlias pattern in favor of combined methods
• Add a short explainer paragraph comparing the methods:
  • What each does
  • Which key types they support (e.g., setECDSAKeyWithAlias is ECDSA-only; setKeyWithAlias supports both ED25519 and ECDSA)
  • Typical use cases
• Ensure docs align with agreed terminology for EVM address context (e.g., “EVM Address derived from public key” vs “derived from account ID”)
• After recommendation is finalized (see related issue), update the primary code snippet on the page accordingly,# Summary
  A definitive recommendation is needed for which method(s) to use in code samples across the docs when creating accounts with an alias.

Context

• The Dev Playground uses setECDSAKeyWithAlias.
• setECDSAKeyWithAlias only applies to ECDSA keys.
• setKeyWithAlias works for both ED25519 and ECDSA keys.
• The docs currently mix setKey, setAlias, and setKeyWithAlias. setKey is deprecated and should be avoided in samples.

Discussion Highlights

"Last I recall this was recommend setECDSAKeyWithAlias."

"The issue with using .setECDSAKeyWithAlias is that it only works for ECDSA keys... From a docs perspective we need to show samples that work for both. So that means either we show two code samples ... or we just show one code sample using .setKeyWithAlias."

Options to Decide

• Option A (ECDSA-first):
  • Primary sample: setECDSAKeyWithAlias (ECDSA)
  • Secondary sample: setKeyWithAlias (ED25519)
• Option B (One-size):
  • Single sample: setKeyWithAlias that works for both ED25519 and ECDSA

Action Items

• Choose the recommended approach (Option A or Option B)
• Update all relevant docs pages and code snippets to use the chosen approach
• Ensure Dev Playground, quickstarts, and tutorials reflect the same recommendation
• Remove/replace any remaining samples using deprecated setKey

Example Snippets (for reference)

• ECDSA-only:
  js
  new AccountCreateTransaction()
  .setECDSAKeyWithAlias(publicKey)
  .execute(client)

• Cross-key (ED25519 or ECDSA):
  js
  new AccountCreateTransaction()
  .setKeyWithAlias(publicKey)
  .execute(client),# Summary
  Add documentation explaining how to derive EVM addresses from keys and existing accounts, including correct use of toEvmAddress() and the need to call AccountId.populateAccountEvmAddress(client) when starting from an AccountId.

Context

• Developers frequently need the EVM address corresponding to an account.
• When calling toEvmAddress() directly on an AccountId string for an existing account, the result can be the long zero address unless the EVM address has been populated from Mirror Node.
• A helper call AccountId.populateAccountEvmAddress(client) exists to fetch and set the correct EVM address for the account.
• There is an upcoming change where the long zero address cannot be used for secp256k1 (ECDSA) accounts, increasing the importance of correct usage.

Discussion Highlights

"The big piece missing from our docs is an explanation of the toEvmAddress helper function."

"You need to call an async AccountId.populateAccountEvmAddress() for it to work correctly."

"It's pretty common and some devs skip the populate step and go straight to .toEvmAddress, which can result in the incorrect address being used."

What to Document

• Deriving from a known public key (typical during account creation; no populate needed):
  js
  const evmAddress = publicKey.toEvmAddress();

• Deriving from an existing account ID (must populate first):
  js
  const evmAddress = (
  await AccountId.fromString("0.0.1234").populateAccountEvmAddress(client)
  ).toEvmAddress();

• Explain that calling AccountId.fromString("0.0.1234").toEvmAddress() without populate returns the long zero address if the EVM address is not already known locally.

• Clarify terminology:

  • “EVM Address derived from public key” (used during account creation when key is available)
  • “EVM Address derived from account ID” (requires Mirror Node fetch via populateAccountEvmAddress)

Action Items

• Add a new subsection on the account creation page (and/or a shared SDK utilities page) covering EVM address derivation
• Include both derivation flows with code samples and cautions about the long zero address
• Audit existing docs and update any examples that call .toEvmAddress() on AccountId without populate
• Note the impact of the forthcoming change disallowing long zero addresses for secp256k1 accounts,# Summary
  Clarify and communicate the deprecation status of AccountCreateTransaction.setKey and evaluate whether setAlias should also be deprecated or retained, then align docs and SDK references with an official process.

Context

• setKey is marked deprecated in the SDK and should be discouraged in docs, although it still functions.
• There is confusion about setAlias because it is typically paired with setKey; combined methods (setKeyWithAlias, setECDSAKeyWithAlias) reduce this need.
• Prior discussions referenced a working group and HIP-1082 context; HIP-1082 remains in draft, and internal decisions predate the Hiero transition.
• The community deprecation communication may be incomplete or unclear.

References:

• HIP-1082: Allow Setting of EVM Address by EOA hiero-ledger/hiero-improvement-proposals#1082
• Related docs page: https://docs.hedera.com/hedera/sdks-and-apis/sdks/accounts-and-hbar/create-an-account

Discussion Highlights

"Was there any official decision to deprecate .setKey? Did we announce it?"

"Maybe we need to go back and do some cleanup... and do this in the new Hiero way so people in the community are actually aware of the deprecation and stop using it."

"Would we include setKey in the methods table... or do we just remove all mentions from docs?" — "We can list that it is deprecated and what they should use instead."

Action Items

• Confirm and document the official deprecation of setKey across SDKs (annotations/JSDoc, release notes, changelogs)
• Decide on the status of setAlias (retain with guidance vs. deprecate) and document rationale
• Update docs to clearly label deprecations and provide explicit migration guidance (e.g., prefer setKeyWithAlias / setECDSAKeyWithAlias)
• Align with Hiero deprecation/communication process and publish an announcement/changelog entry
• Audit tutorials and samples to remove or replace uses of setKey