Transfer to unregistered recipient

Transfer to a recipient who has not registered a private address yet. The send uses a derived escrow note and stays indistinguishable from a private transfer.

Disclosure policy

Sender may be public or private. Private sender and this escrow send both require Protocol Relay. Recipient, asset, and amount stay private.

Transact environment hooks

Unregistered recipients need resolveTransferRecipientAtExecute on transactEnvironment. The default chain resolver (resolveTransferRecipientFromChain) looks up the registry, then derives an escrow key from a random nonce and the recipient’s Stellar G-address. That pins exactly one recipient to the note. Public escrow recipient limbs stay zero on send, so the transaction matches an ordinary private transfer. The hook is registered during client bootstrap (see Setup). Use a client slot assigned after createStellarPrivacyClient — do not close over client before it exists. Custom resolvers should return escrowSend with the derived nonce and G-address limbs rather than a temporary private address.

import type { StellarPrivacyClient } from '@arcanetech/privacy-sdk-stellar';

let privacyClient: StellarPrivacyClient | undefined;

const transactEnvironment = {
  // ...network, kyt, signTransaction from setup
  resolveTransferRecipientAtExecute: async ({
    recipientStellarAddress,
    walletPublicKey,
  }) => {
    if (!privacyClient) {
      throw new Error('Privacy client is not ready.');
    }
    return privacyClient.resolveTransferRecipient({
      recipientStellarAddress,
      walletPublicKey,
    });
  },
};

// after createStellarPrivacyClient succeeds:
privacyClient = created;

Escrow sends require Protocol Relay and a zero public deposit. A positive public deposit is refused (not downgraded to Direct Submission). If relay is unconfigured, submission fails with escrow_relay_unconfigured and wallet submission is not offered. operation.execute() is Direct Submission and does not complete an escrow send.

Example

The addresses, contracts, and seed values below are placeholders, not runnable testnet data. Use the matching pool configuration and audit public key from Set up the SDK. Create the client using Frontend integration or Backend integration, and load real account state as described in State methods.

Call transfer with a public Stellar to address and the same private disclosure as a registered transfer.

Seed state

const POOL = 'CBVQTSTSIJ4UZMN5FQBFHPUIYSW3ATGSP57BZDJNKTOBNQODQTRGE4K5';
const SENDER = 'GDSENDER7EXAMPLEPUBLICKEYAAAAAAAAAAAAAAAAAAAA';
const SENDER_PRIVATE = 'stpl1sender7exampleprivateaddress0000000000';
const RECIPIENT = 'GCRECIPIENT7EXAMPLEPUBLICKEYAAAAAAAAAAAAAAA';

await client.upsertAssets([
  {
    id: 1,
    assetId: 'usdc',
    name: 'USDC',
    logoUrl: null,
    issuerAddress: null,
    clientContract: 'CTOKENCONTRACTEXAMPLEAAAAAAAAAAAAAAAAAAAAAA',
    poolContracts: [POOL],
    poolContract: POOL,
    mintable: false,
    mintAmount: null,
  },
]);
await client.saveRegistryLookup({ owner: RECIPIENT, status: 'unregistered' });
await client.setPoolMerkleState({
  poolContract: POOL,
  commitments: ['0xmerklecommitmenthexexample00000000000000000000000000000000'],
  commitmentCount: 1,
  merkleRootHex: '0xmerkleroothexexample000000000000000000000000000000000000',
  updatedAt: Date.now(),
});
await client.saveWalletPrivateAddressRecord({
  owner: SENDER,
  nonce: '1',
  privateAddress: SENDER_PRIVATE,
  createdAt: Date.now(),
});
await client.saveWalletPrivateAddressScalar({
  owner: SENDER,
  nonce: '1',
  scalarHex: '0xabc123scalarhexexample000000000000000000000000000000000000',
});
await client.setWalletDefaultPrivateAddressNonce({ owner: SENDER, nonce: '1' });
await client.upsertPrivateRecords([
  {
    id: '0xnotecommitmenthexexample000000000000000000000000000000000000',
    owner: SENDER,
    privateAddress: SENDER_PRIVATE,
    asset: 'usdc',
    amount: 100_0000000n,
    consumed: false,
    poolContract: POOL,
    coinNote: {
      value: '1000000000',
      nullifier: '0xnullifierhexexample000000000000000000000000000000000000',
      secret: '0xsecrethexexample0000000000000000000000000000000000000000',
      commitment: '0xnotecommitmenthexexample000000000000000000000000000000000000',
      asset_hi: '0xassethihexexample00000000000000000000000000000000000000',
      asset_lo: '0xassetlohexexample00000000000000000000000000000000000000',
    },
  },
]);

Run operation

import { requiredSubmissionMethod } from '@arcanetech/privacy-sdk-stellar/transact';
import {
  createRelayApi,
  resolveRelayOrigin,
  submitAndAwaitPrivateOperation,
  throwIfRelayUnsuccessful,
} from '@arcanetech/privacy-sdk-relay';

const operation = await client.transfer({
  from: 'stpl1sender7exampleprivateaddress0000000000',
  to: 'GCRECIPIENT7EXAMPLEPUBLICKEYAAAAAAAAAAAAAAA',
  asset: 'usdc',
  amount: 25_0000000n,
  disclosure: {
    senderAddress: 'private',
    recipientAddress: 'private',
    assetAddress: 'private',
    amount: 'private',
  },
});

if (operation.status === 'rejected') {
  throw new Error(operation.errors[0]?.message);
}

// Use the same environment passed when creating the client.
const zkConfigNonce = transactEnvironment.zkConfigNonce;
if (zkConfigNonce === undefined) {
  throw new Error('Configure the nonce for your deployed pool.');
}
const method = requiredSubmissionMethod(operation.prepared, zkConfigNonce);
if (method !== 'relay') {
  throw new Error('Escrow sends must use Protocol Relay.');
}

// Implement store, submitDirect, finalizeLocalState, drainDeliveries,
// persistUserTransaction, and relayOperation in your app — see the
// Frontend / Backend demos for complete ports.
const origin = resolveRelayOrigin(relayOriginFromEnv);
const ports = {
  store,
  submitDirect,
  finalizeLocalState,
  drainDeliveries,
  persistUserTransaction,
  ...(origin
    ? { relayConfig: { origin }, relayApi: createRelayApi({ origin }) }
    : {}),
};
const result = await submitAndAwaitPrivateOperation({
  ports,
  operation: relayOperation,
});
throwIfRelayUnsuccessful(result);

Build relayOperation from operation.prepared (prepareRelayTransactPackageFromPrepared + serializeRelayPackage, submissionPath: 'relay'). Complete port implementations: Examples. The SDK derives the escrow note owner at execute-time resolution. It does not put the recipient G-address in pool calldata or the relay package on send.

Discover notes sent before registration

A recipient who registers later can still find notes that were sent to their public wallet. Escrow discovery uses blinded recipient tags, not the retired pending-claim client API. Your stand may provide a tag-issuance / storage origin. Production apps often fetch the challenge and issued tags from that service, then sign the challenge with the wallet. When your app builds the challenge string locally, use buildBlindedRecipientTagChallengeMessage so the UTF-8 bytes match issuance (same labeled-line shape as a private-note spend key). Sign the message with a current account signer, then present the signature to your tag-issuance integration. Issued blinded recipient tags (one per tag epoch) are how the recipient looks up notes without revealing their address to the index. To claim a discovered note, fetchEscrowOutputNoteEvents reads the output-note ciphertexts through the existing transact environment (do not pass an RPC URL). After proving the sweep, submit it with Direct Submission: the claimant wallet is from and signs the transaction envelope. Protocol Relay is not used for sweeps.

import { buildBlindedRecipientTagChallengeMessage } from '@arcanetech/privacy-sdk-stellar/transact';

const message = buildBlindedRecipientTagChallengeMessage({
  stellarAddress: walletPublicKey,
  networkPassphrase: transactEnvironment.network.networkPassphrase,
  issuedAt,
  expiresAt,
  nonce,
});
const signature = await wallet.authorizeMessage(message);

Do not reconstruct the message by hand. Issuance verifies the signed string byte-for-byte.

Examples

Explore the frontend and backend reference applications.

State methods

Seed state is a doc fixture; production data flows.

Disclosure policy

Private escrow disclosure constraints.

Introduction

Compliance Platform

Privacy Layer

Custom KYT providers

Support

Transfer to unregistered recipient

Disclosure policy

Transact environment hooks

Example

Seed state

Run operation

Discover notes sent before registration

Examples

State methods

Disclosure policy

​Disclosure policy

​Transact environment hooks

​Example

​Seed state

​Run operation

​Discover notes sent before registration

​Related

Examples

State methods

Disclosure policy

Disclosure policy

Transact environment hooks

Example

Seed state

Run operation

Discover notes sent before registration

Related