sta-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,484 @@
+import { Keypair, SigningCallback, xdr, Transaction, rpc } from '@stellar/stellar-sdk';
+export { Account } from '@stellar/stellar-sdk';
+
+/**
+ * Network configuration for `sta-sdk`.
+ *
+ * `testnet` is populated with the live, currently-deployed contract set --
+ * the `smart_account` address is the account_factory-deployed treasury from
+ * the smart-contracts repo's docs/TESTNET_FACTORY_DEPLOYMENT.md §13.2,
+ * which runs the fixed contract code (see docs/SECURITY_REVIEW_STRICT.md
+ * finding 29). The older hand-deployed treasury from docs/TESTNET_DEPLOYMENT.md
+ * predates that fix and is not the default here.
+ *
+ * `MAINNET` stays `undefined` until `buildMainnetConfig` is actually called
+ * with real, deployed contract addresses -- no mainnet deployment exists
+ * yet, and nothing here fabricates one. What *is* ready now is the rest of
+ * the mainnet shape: the real, verified mainnet network passphrase
+ * (`MAINNET_NETWORK_PASSPHRASE`, a fixed protocol constant, unlike an RPC
+ * URL) and `buildMainnetConfig` itself, so wiring in a real mainnet
+ * deployment later is "call this function with the six addresses," not a
+ * code change.
+ */
+interface ContractAddresses {
+    smartAccount: string;
+    policyEngine: string;
+    intentRegistry: string;
+    recoveryManager: string;
+    accountFactory: string;
+    /** Never called directly by a client (see docs/DAPP_INTEGRATION_SPEC.md
+     * §1) -- recorded for reference and for building auth-entry
+     * sub-invocations by hand. */
+    transferAdapter: string;
+    splitAdapter: string;
+}
+interface NetworkConfig {
+    network: "testnet" | "mainnet";
+    rpcUrl: string;
+    networkPassphrase: string;
+    contracts: ContractAddresses;
+}
+declare const TESTNET: NetworkConfig;
+/**
+ * Stellar's mainnet (Public Network) passphrase -- a fixed protocol
+ * constant defined by the network itself (verified against
+ * https://developers.stellar.org/docs/encyclopedia/network-passphrases),
+ * not something that depends on which contracts (if any) are deployed.
+ * Safe to hardcode, unlike a mainnet RPC URL (see `buildMainnetConfig`).
+ */
+declare const MAINNET_NETWORK_PASSPHRASE = "Public Global Stellar Network ; September 2015";
+/**
+ * Unlike testnet (SDF hosts `https://soroban-testnet.stellar.org` for
+ * free), SDF does **not** operate a free public mainnet Soroban RPC
+ * endpoint -- confirmed against
+ * https://developers.stellar.org/docs/data/apis/rpc/providers, which
+ * lists only third-party ecosystem providers (QuickNode, Ankr, Tatum,
+ * Blockdaemon, etc.) for mainnet. There is no single correct default to
+ * hardcode here, so `buildMainnetConfig` reads this env var instead of
+ * assuming a provider on your behalf -- set it to whichever provider's
+ * URL you've chosen, or pass `rpcUrl` to that function directly.
+ */
+declare const MAINNET_RPC_URL_ENV = "STA_MAINNET_RPC_URL";
+/**
+ * Builds a mainnet `NetworkConfig` once the contracts are actually deployed
+ * there. No mainnet deployment exists yet -- this function exists so this
+ * module is ready to receive real mainnet addresses the moment a
+ * deployment happens, not to fabricate one now.
+ *
+ * A `NetworkConfig` with `network: "mainnet"` and real signing keys
+ * submits real, fee-paying, fund-moving transactions against Stellar's
+ * production ledger -- don't build one just to "try it out" with testnet
+ * addresses.
+ *
+ * @param contracts The six real contract addresses from an actual mainnet
+ *   deployment record (mirroring how `TESTNET.contracts` above is sourced
+ *   from the smart-contracts repo's docs/TESTNET_FACTORY_DEPLOYMENT.md).
+ * @param rpcUrl Your chosen mainnet RPC provider's URL. Defaults to
+ *   `process.env[MAINNET_RPC_URL_ENV]`; throws if neither is supplied,
+ *   rather than silently falling back to some hardcoded provider.
+ */
+declare function buildMainnetConfig(contracts: ContractAddresses, rpcUrl?: string): NetworkConfig;
+/** `undefined` until `buildMainnetConfig` is actually called with real,
+ * deployed contract addresses -- see this module's doc comment and that
+ * function's. No mainnet deployment exists yet. */
+declare const MAINNET: NetworkConfig | undefined;
+declare const NETWORKS: {
+    readonly testnet: NetworkConfig;
+    readonly mainnet: undefined;
+};
+
+/**
+ * `smart_account`'s custom-account authorization: "Entry A" / "Entry B"
+ * construction ("sta-sdk").
+ *
+ * Deliberately does not depend on the Stellar CLI's generated per-contract
+ * bindings (`stellar contract bindings typescript`) for this encoding:
+ * those bindings pin to a specific `@stellar/stellar-sdk` major, and
+ * loading a second major of the same classes (`Address`, `xdr.ScVal`, ...)
+ * in a consumer's bundle risks `instanceof` mismatches between them. This
+ * module hand-encodes the `AuthPayload` struct shape directly instead
+ * (`smartAccountAuthPayloadScVal` below), verified against the real
+ * `#[contracttype]` definition (`{ signers: Map<Signer, Bytes>,
+ * context_rule_ids: Vec<u32> }`) rather than derived from a generated
+ * client's `Spec`.
+ *
+ * `smart_account` implements Soroban's `CustomAccountInterface`
+ * (`__check_auth`), composed from OpenZeppelin's `stellar-accounts` crate.
+ * Any call that does `env.current_contract_address().require_auth()` --
+ * every fund-moving or schedule-creating entrypoint -- needs the
+ * transaction to carry a `SorobanAuthorizationEntry` whose
+ * `credentials.signature` is not a signature at all, but a
+ * contract-defined `AuthPayload` struct.
+ *
+ * Two entries are required per required `Signer::Delegated` signer:
+ *
+ * - **Entry A** (once, for `smart_account` itself): the `AuthPayload`
+ *   structure -- no wallet interaction, assembled directly from the
+ *   caller-supplied context rule id(s).
+ * - **Entry B** (one per required signer): a standard classic-account
+ *   authorization entry for the nested
+ *   `addr.require_auth_for_args((auth_digest,))` call -- this is what a
+ *   wallet (or a raw `Keypair`, server-side) actually signs, via
+ *   `@stellar/stellar-sdk`'s own `authorizeEntry`.
+ */
+
+interface SubInvocationSpec {
+    contractId: string;
+    functionName: string;
+    args: xdr.ScVal[];
+    subInvocations?: xdr.SorobanAuthorizedInvocation[];
+}
+declare function buildInvocation(spec: SubInvocationSpec): xdr.SorobanAuthorizedInvocation;
+/** The standard Soroban authorization-entry signature payload: the hash of
+ * the `HashIdPreimage::SorobanAuthorization` preimage over a given
+ * invocation, nonce, and expiration ledger. Every `Address` credential
+ * (custom-account or classic) signs a value derived from this. */
+declare function signaturePayload(invocation: xdr.SorobanAuthorizedInvocation, nonce: bigint, signatureExpirationLedger: number, networkPassphrase: string): Buffer;
+interface BuildSmartAccountAuthOptions {
+    smartAccountId: string;
+    /** The actual `smart_account` call being authorized (its root
+     * invocation) -- e.g. `execute_transfer_payment(...)`. Declare any
+     * further sub-invocations that must be pre-cleared by this SAME entry
+     * as its `subInvocations`. */
+    rootInvocation: xdr.SorobanAuthorizedInvocation;
+    /** G-address of the `Signer::Delegated` wallet authorizing this call. */
+    signerAddress: string;
+    /** Signs Entry B's classic authorization entry -- a raw `Keypair` for
+     * server-side use, or a `SigningCallback` forwarding to a connected
+     * wallet's `signAuthEntry`. */
+    sign: Keypair | SigningCallback;
+    networkPassphrase: string;
+    /** Context rule id(s) the signer is registered under, one per auth
+     * context reaching `__check_auth` (root + any declared
+     * sub-invocation). Default: `[0]` (the founding rule), applied to every
+     * context. */
+    contextRuleIds?: number[];
+    signatureExpirationLedger: number;
+}
+/**
+ * Builds Entry A + Entry B for a single required `Signer::Delegated`.
+ *
+ * KNOWN ISSUE: for a multi-signer context rule (threshold > 1), calling
+ * this once per signer and attaching each pair produces N separate
+ * Entry As, each with a single-key `signers` map. That does not match
+ * `DAPP_INTEGRATION_SPEC.md` §5.4, which specifies one shared Entry A
+ * carrying all N signers' keys plus N Entry Bs (one per signer) collected
+ * against that same Entry A over time. Multi-signer callers should not
+ * rely on this function as-is until that's reconciled -- track before
+ * shipping real M-of-N threshold support.
+ */
+declare function buildSmartAccountAuthEntries(opts: BuildSmartAccountAuthOptions): Promise<[xdr.SorobanAuthorizationEntry, xdr.SorobanAuthorizationEntry]>;
+interface BuildExecutorAuthOptions {
+    intentRegistryId: string;
+    intentId: Buffer;
+    childSequence: number;
+    executorAddress: string;
+    sign: Keypair | SigningCallback;
+    networkPassphrase: string;
+    signatureExpirationLedger: number;
+}
+/**
+ * Authorizes `intent_registry.mark_child_executed`, the *only* real
+ * authorization check in `execute_scheduled_payment`'s whole call graph.
+ *
+ * `SourceAccount`/auto-fill credentials only cover a `require_auth()` at
+ * the ROOT of the invocation tree; `mark_child_executed`'s
+ * `executor.require_auth()` is two levels deep (`execute_scheduled_payment
+ * -> intent_registry.mark_child_executed -> ensure_executor`), so it needs
+ * an explicit entry, built and signed the same way as any other non-root
+ * classic-account authorization -- this is *not* custom-account machinery
+ * (the executor is a plain account), so no `AuthPayload`/Entry-A-Entry-B
+ * pairing is involved, just one ordinary signed entry rooted directly at
+ * `mark_child_executed`. Verified against live testnet (see the
+ * smart-contracts repo's docs/TESTNET_FACTORY_DEPLOYMENT.md §8 and
+ * docs/DAPP_INTEGRATION_SPEC.md §8), and independently against this same
+ * failure mode in this dApp's own `src/lib/relayer/executor.ts`.
+ */
+declare function buildExecutorAuthEntry(opts: BuildExecutorAuthOptions): Promise<xdr.SorobanAuthorizationEntry>;
+
+/**
+ * Transaction-preparation helpers: prepare -> simulate -> approve. Each
+ * function returns a prepared, auth-entry-attached `Transaction` --
+ * simulated (fee/resource estimation) with the custom `smart_account`
+ * `AuthPayload` entries already present, ready for the caller to sign the
+ * envelope with a fee-paying account and submit (see `signAndSubmit`
+ * below). None of these functions touch a wallet directly -- signing is
+ * always an injected `Keypair | SigningCallback` (see `auth.ts`), so a
+ * browser dApp can swap in a connected wallet's `signAuthEntry` without
+ * changing anything here.
+ *
+ * Call args are hand-encoded (`transferArgs`, `splitArgs`,
+ * `scheduledIntentScVal`, below) against the contracts' real signatures,
+ * rather than through a generated-bindings client's
+ * `.spec.funcArgsToScVals(...)` -- see `auth.ts`'s module doc comment for
+ * why this SDK avoids depending on those generated bindings directly.
+ */
+
+interface PrepareOptions {
+    net: NetworkConfig;
+    /** Any funded account that pays the network fee -- independent of who
+     * authorizes the `smart_account` call. Only its public key is needed to
+     * build the transaction. */
+    feeSourceAddress: string;
+    signerAddress: string;
+    sign: Keypair | SigningCallback;
+    contextRuleIds?: number[];
+}
+interface TransferPaymentArgs {
+    asset: string;
+    destination: string;
+    amount: bigint;
+    nonce: bigint;
+    expectedPolicyVersion: number;
+}
+declare function prepareTransferPayment(opts: PrepareOptions, payment: TransferPaymentArgs): Promise<Transaction>;
+interface SplitPaymentArgs {
+    asset: string;
+    recipients: string[];
+    amounts: bigint[];
+    nonce: bigint;
+    expectedPolicyVersion: number;
+}
+declare function prepareSplitPayment(opts: PrepareOptions, payment: SplitPaymentArgs): Promise<Transaction>;
+interface ScheduledIntentArgs {
+    intent_id: Buffer;
+    asset: string;
+    destination: string;
+    amount: bigint;
+    start_ledger: number;
+    end_ledger: number;
+    interval_ledgers: number;
+    max_executions: number;
+    /** Ignored/overwritten server-side, pinned to `0` at creation -- pass any
+     * placeholder value; read the resolved field back from the
+     * `IntentCreated` event or a follow-up `get_intent` read. */
+    execution_count: number;
+    /** Ignored/overwritten server-side, pinned to `policy_engine.version()`
+     * at creation time -- see `execution_count` above. */
+    policy_version: number;
+    /** Ignored/overwritten server-side, pinned to the currently configured
+     * `transfer_adapter` at creation time -- see `execution_count` above. */
+    adapter: string;
+    cancelled: boolean;
+}
+/** `intent`'s caller-supplied `policy_version`/`adapter` are ignored and
+ * overwritten by the contract (pinned to current values at approval time)
+ * -- pass any placeholder value; read the resolved fields back from the
+ * `IntentCreated` event or a follow-up `get_intent` read. */
+declare function prepareScheduledPayment(opts: PrepareOptions, intent: ScheduledIntentArgs): Promise<Transaction>;
+declare function prepareCancelScheduledPayment(opts: PrepareOptions, intentId: Buffer): Promise<Transaction>;
+/** Signs the transaction envelope with the fee-paying account's key
+ * (independent of the `smart_account` auth entries, already attached by
+ * `prepare*`) and submits it, polling until a terminal status. */
+declare function signAndSubmit(net: NetworkConfig, tx: Transaction, feeSourceKeypair: Keypair): Promise<rpc.Api.GetSuccessfulTransactionResponse>;
+interface RelayerExecuteOptions {
+    net: NetworkConfig;
+    intentId: Buffer;
+    childSequence: number;
+    executorAddress: string;
+    sign: Keypair | SigningCallback;
+}
+/**
+ * Prepares a relayer's `execute_scheduled_payment` call. Unlike the
+ * signer-authored payment helpers above, this needs no `smart_account`
+ * `AuthPayload` at all -- only an explicit authorization entry for
+ * `intent_registry.mark_child_executed`'s `Executor` requirement (see
+ * `buildExecutorAuthEntry`'s doc comment in `auth.ts`).
+ */
+declare function prepareRelayerExecution(opts: RelayerExecuteOptions): Promise<Transaction>;
+
+/**
+ * Typed event parsing. Depends only on `@stellar/stellar-sdk`'s
+ * `xdr`/`scValToNative` -- no generated per-contract bindings involved.
+ * Keep in sync by hand if the source contracts' `#[contractevent]`
+ * definitions change — there is no automated link between this package
+ * and the contracts repo.
+ *
+ * The Stellar CLI's generated bindings expose function signatures, errors,
+ * and structs from a contract's spec, but not its `#[contractevent]`
+ * definitions — those are hand-typed here, against the actual struct
+ * definitions in each contract's `src/lib.rs`, and are exposed as
+ * first-class types rather than raw event XDR.
+ *
+ * Every `#[contractevent]` struct is encoded on-chain as: topics[0] = the
+ * event's short topic symbol (see the smart-contracts repo's
+ * docs/DAPP_INTEGRATION_SPEC.md §10.4), followed by any further
+ * `#[topic]`-tagged fields, then a data map of the remaining fields keyed
+ * by their Rust field name.
+ */
+
+interface TransferPaid {
+    asset: string;
+    destination: string;
+    amount: bigint;
+    nonce: bigint;
+}
+interface SplitPaid {
+    asset: string;
+    recipient_count: number;
+    nonce: bigint;
+}
+interface ScheduledPaymentExecuted {
+    intent_id: Buffer;
+    child_sequence: number;
+    asset: string;
+    destination: string;
+    amount: bigint;
+}
+interface PolicyValidated {
+    operation: string;
+    asset: string;
+    destination: string;
+    amount: bigint;
+    expected_version: number;
+}
+interface IntentCreated {
+    intent_id: Buffer;
+}
+interface IntentCancelled {
+    intent_id: Buffer;
+}
+interface ChildExecuted {
+    intent_id: Buffer;
+    child_sequence: number;
+}
+interface RecoveryOpened {
+    request_id: Buffer;
+}
+interface RecoveryApproved {
+    request_id: Buffer;
+    guardian: string;
+}
+interface RecoveryFinalized {
+    request_id: Buffer;
+    replacement_owner: string;
+}
+interface RecoveryApplied {
+    request_id: Buffer;
+    replacement_owner: string;
+}
+interface GuardianFreezeRequested {
+    guardian: string;
+}
+interface Frozen {
+    triggered_by_guardian: boolean;
+}
+/** Every event type this module knows how to decode, keyed by its on-chain
+ * topic symbol. Add new entries here as new contract events are curated. */
+interface EventMap {
+    pay_ok: TransferPaid;
+    splt_ok: SplitPaid;
+    auto_ok: ScheduledPaymentExecuted;
+    pol_ok: PolicyValidated;
+    intent: IntentCreated;
+    cancel: IntentCancelled;
+    exec: ChildExecuted;
+    open: RecoveryOpened;
+    appr: RecoveryApproved;
+    final: RecoveryFinalized;
+    recover: RecoveryApplied;
+    gfreeze: GuardianFreezeRequested;
+    frozen: Frozen;
+}
+type ParsedEvent = {
+    [K in keyof EventMap]: {
+        topic: K;
+        event: EventMap[K];
+    };
+}[keyof EventMap] | {
+    topic: string;
+    event: Record<string, unknown>;
+};
+/** Parses one `xdr.ContractEvent` into its typed shape, matched by topic,
+ * merging `#[topic]`-tagged fields (from `topics[1..]`) with the data map
+ * -- both are needed to reconstruct the full `#[contractevent]` struct.
+ * Unknown topics still parse -- as `{ topic, event: <raw decoded map> }`
+ * -- rather than throwing, so a caller can log/inspect an event this
+ * module doesn't have a named type for yet. */
+declare function parseContractEvent(event: xdr.ContractEvent): ParsedEvent;
+/** Parses every event from a `getTransaction` response's
+ * `events.contractEventsXdr` (one array of events per operation -- this
+ * dApp's transactions always have exactly one operation, so pass
+ * `contractEventsXdr[0]`). */
+declare function parseContractEvents(events: xdr.ContractEvent[]): ParsedEvent[];
+declare function findEvent<T extends keyof EventMap>(events: ParsedEvent[], topic: T): EventMap[T] | undefined;
+
+interface AccountStatus {
+    initialized: boolean;
+    paused: boolean;
+    frozen: boolean;
+    policy_version_hint: number;
+}
+/** From the vendored `stellar-accounts` OZ crate
+ * (`smart_account::storage::ContextRule`), not this workspace's own
+ * contracts -- `get_context_rule`'s actual return type. */
+interface ContextRule {
+    id: number;
+    context_type: string;
+    name: string;
+    signers: unknown[];
+    signer_ids: number[];
+    policies: string[];
+    policy_ids: number[];
+    valid_until?: number;
+}
+interface ScheduledIntent {
+    intent_id: Buffer;
+    asset: string;
+    destination: string;
+    amount: bigint;
+    start_ledger: number;
+    end_ledger: number;
+    interval_ledgers: number;
+    max_executions: number;
+    execution_count: number;
+    policy_version: number;
+    adapter: string;
+    cancelled: boolean;
+}
+interface RecoveryRequest {
+    request_id: Buffer;
+    replacement_owner: string;
+    replacement_signers: unknown[];
+    replacement_policies: Record<string, unknown>;
+    earliest_ledger: number;
+    approvers: string[];
+    cancelled: boolean;
+    finalized: boolean;
+}
+interface WasmHashes {
+    policy_engine: Buffer;
+    intent_registry: Buffer;
+    recovery_manager: Buffer;
+    transfer_adapter: Buffer;
+    split_adapter: Buffer;
+    smart_account: Buffer;
+}
+/** `smart_account.status()` -- check before offering any payment action; a
+ * paused or frozen treasury should disable the payment UI, not let the
+ * user hit a rejected simulation. */
+declare function readAccountStatus(net: NetworkConfig, sourceAddress: string): Promise<AccountStatus>;
+declare function readOwner(net: NetworkConfig, sourceAddress: string): Promise<string | null>;
+/** Rule IDs are `0..count`, not necessarily contiguous after removals --
+ * check existence with `readContextRule`, don't assume. */
+declare function readContextRulesCount(net: NetworkConfig, sourceAddress: string): Promise<number>;
+declare function readContextRule(net: NetworkConfig, sourceAddress: string, contextRuleId: number): Promise<ContextRule>;
+declare function isNonceUsed(net: NetworkConfig, sourceAddress: string, nonce: bigint): Promise<boolean>;
+/** The authoritative current policy version -- read fresh immediately
+ * before building a payment, never cached across a user session (a stale
+ * value here causes a clean `VersionMismatch` rejection rather than
+ * executing under outdated rules). */
+declare function readPolicyVersion(net: NetworkConfig, sourceAddress: string): Promise<number>;
+declare function readScheduledIntent(net: NetworkConfig, sourceAddress: string, intentId: Buffer): Promise<ScheduledIntent>;
+declare function isChildExecuted(net: NetworkConfig, sourceAddress: string, intentId: Buffer, childSequence: number): Promise<boolean>;
+/** Recovery-request state -- first-class typed state, not a raw XDR blob. */
+declare function readRecoveryRequest(net: NetworkConfig, sourceAddress: string, requestId: Buffer): Promise<RecoveryRequest>;
+declare function readLiveApprovalCount(net: NetworkConfig, sourceAddress: string, requestId: Buffer): Promise<number>;
+declare function isGuardian(net: NetworkConfig, sourceAddress: string, guardian: string): Promise<boolean>;
+/** Monotonically increasing, never-cleared -- compare against a locally
+ * stored "last applied" value to detect a pending guardian freeze rather
+ * than treating this as a boolean. */
+declare function readGuardianFreezeEpoch(net: NetworkConfig, sourceAddress: string): Promise<number>;
+declare function readFactoryWasmHashes(net: NetworkConfig, sourceAddress: string): Promise<WasmHashes>;
+
+export { type AccountStatus, type BuildExecutorAuthOptions, type BuildSmartAccountAuthOptions, type ChildExecuted, type ContextRule, type ContractAddresses, type EventMap, type Frozen, type GuardianFreezeRequested, type IntentCancelled, type IntentCreated, MAINNET, MAINNET_NETWORK_PASSPHRASE, MAINNET_RPC_URL_ENV, NETWORKS, type NetworkConfig, type ParsedEvent, type PolicyValidated, type PrepareOptions, type RecoveryApplied, type RecoveryApproved, type RecoveryFinalized, type RecoveryOpened, type RecoveryRequest, type RelayerExecuteOptions, type ScheduledIntent, type ScheduledIntentArgs, type ScheduledPaymentExecuted, type SplitPaid, type SplitPaymentArgs, type SubInvocationSpec, TESTNET, type TransferPaid, type TransferPaymentArgs, type WasmHashes, buildExecutorAuthEntry, buildInvocation, buildMainnetConfig, buildSmartAccountAuthEntries, findEvent, isChildExecuted, isGuardian, isNonceUsed, parseContractEvent, parseContractEvents, prepareCancelScheduledPayment, prepareRelayerExecution, prepareScheduledPayment, prepareSplitPayment, prepareTransferPayment, readAccountStatus, readContextRule, readContextRulesCount, readFactoryWasmHashes, readGuardianFreezeEpoch, readLiveApprovalCount, readOwner, readPolicyVersion, readRecoveryRequest, readScheduledIntent, signAndSubmit, signaturePayload };