Shadow Accounts

Shadow accounts give one user a persistent, pseudonymous identity for one dapp. They are useful for positions that live across transactions - staking, lending, rewards, and any protocol that needs to recognize a returning caller.

This page follows Privacy SDK 0.14.3-rc.8. The old subaccounts(...) API was renamed and is not compatible with the current anonymizer. Use shadowAccounts(...) throughout.

Snippets assume transfers, account and provider from Getting Started.

Configure the anonymizer

Pass the deployment for the connected network when creating transfers:

const transfers = createPrivateTransfers({
  account,
  viewingKeyProvider,
  provingProvider,
  discoveryProvider,
  poolContractAddress: process.env.POOL_ADDRESS!,
  shadowAccountAnonymizerAddress: process.env.SHADOW_ACCOUNT_ANONYMIZER_ADDRESS!,
})

Calling shadowAccounts(...) without shadowAccountAnonymizerAddress throws. Use the current Mainnet or Sepolia value from Deployed Contract Addresses.

Commitments and addresses

The builder derives the partial and full commitments locally from the user, viewing key, anonymizer, dapp name, and nonce:

import { shadowAccountAddress } from "@starkware-libs/starknet-privacy-sdk"

const shadow = transfers.build().shadowAccounts("myDapp")
const partial = await shadow.partialCommitment()
const commitment = await shadow.commitment(0n)

const address = shadowAccountAddress(
  commitment,
  BigInt(process.env.SHADOW_ACCOUNT_ANONYMIZER_ADDRESS!),
)

shadowAccountAddress uses the exported, fixed PRIMER_CLASS_HASH, matching the current Cairo deployment pattern. It works before the account is deployed and does not require an RPC call. The package also exports the lower-level shadowAccountPartialCommitment and shadowAccountCommitment helpers when you already hold the raw felts.

Invoke through the shadow account

Fund the shadow address, create an open note for each expected output token, then queue the calls. The SDK translates this into one ComputeAndInvoke against the ShadowAccountAnonymizer.

import { Open } from "@starkware-libs/starknet-privacy-sdk"

const provingBlockId = (await provider.getBlockNumber()) - 10

const { callAndProof } = await transfers
  .build({ autoDiscover: { notes: "refresh" } })
  .with(STRK)
  .withdraw({ recipient: address, amount: 5n * 10n ** 18n })
  .surplusTo(account.address, false)
  .with(STRK)
  .transfer({ recipient: account.address, amount: Open })
  .done()
  .shadowAccounts("myDapp")
  .invoke(0n, {
    calls: [stakingContract.populate("stake", { amount: 1000n })],
    collectPolicy: { type: "all" },
  })
  .execute({ provingBlockId })

// Submit callAndProof with the usual proofDetails + tip: 0n tail.

collectPolicy is optional in the SDK and defaults to { type: "all" }.

Read deployed and undeployed accounts

The exported ShadowAccountAnonymizerABI includes these views:

• get_shadow_accounts(partial, start, end, until_undeployed) resolves a nonce range and returns { nonce, address, is_deployed } for each entry.
• get_shadow_account(commitment) returns the stored address of an already deployed account, or zero when it has not been deployed.
• get_shadow_account_class_hash() returns the class installed after the primer deployment. It is not the class hash used for address derivation.

The scan range is limited to 1,024 nonces. With until_undeployed: true, the range stops at the first address that has not been deployed.

Things to notice

• A shadow account's balances, calls, and positions are public. Privacy comes from hiding the link to the user's main account.
• A shadow account has no keys. Only the anonymizer can execute through it.
• One transaction can contain at most one invoke-phase action, whether it is a normal invoke or a shadow-account invocation.
• One collection policy applies to every open note settled by the invocation.
• The current anonymizer returns the shadow-account address used by deposits so the pool can apply its screening policy to that address.

Next: Proving Configuration - prepare and submit the resulting call safely.