@secondlayer/stacks 0.2.1 → 0.3.0

package/dist/src/index.d.ts

@@ -1,3 +1,179 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { ClarityValue, PostCondition } from "@stacks/transactions";
+interface TransferIntent {
+	kind: "transfer";
+	recipient: string;
+	amount: bigint;
+	memo?: string;
+	postConditions?: PostCondition[];
+}
+interface ContractCallIntent {
+	kind: "contract-call";
+	/** Fully-qualified contract id, e.g. `"SP000000000000000000002Q6VF78.bns"`. */
+	contract: string;
+	fn: string;
+	args: ClarityValue[];
+	postConditions?: PostCondition[];
+}
+interface DeployIntent {
+	kind: "deploy";
+	name: string;
+	source: string;
+	clarityVersion?: 1 | 2 | 3;
+}
+interface MultiSendIntent {
+	kind: "multisend";
+	payments: Array<{
+		recipient: string
+		amount: bigint
+		memo?: string
+	}>;
+}
+type TxIntent = TransferIntent | ContractCallIntent | DeployIntent | MultiSendIntent;
+/**
+* Lightweight factory functions for building tx intents. Identity-shaped
+* with a `kind` tag so the broadcast step can discriminate at runtime.
+*/
+declare const tx: {
+	readonly transfer: (opts: Omit<TransferIntent, "kind">) => TransferIntent
+	readonly contractCall: (opts: Omit<ContractCallIntent, "kind">) => ContractCallIntent
+	readonly deploy: (opts: Omit<DeployIntent, "kind">) => DeployIntent
+	readonly multisend: (opts: Omit<MultiSendIntent, "kind">) => MultiSendIntent
+};
+/**
+* Submit a transaction intent to the Stacks network via a workflow-declared
+* signer. The Secondlayer runner intercepts this call to:
+*
+*   1. Resolve `signer` to a `RemoteSignerConfig` (endpoint + publicKey +
+*      hmacRef) declared on the workflow.
+*   2. Fetch the HMAC secret from the runtime secret store.
+*   3. Enforce safety caps (`maxMicroStx`, `maxFee`).
+*   4. POST the unsigned tx breakdown to the customer's signer endpoint.
+*   5. Submit the returned signed tx to the Stacks node.
+*
+* Returns the txId immediately. Confirmation polling lands in Sprint 5 via
+* `awaitConfirmation: true` (no-op today — subgraph-backed path forthcoming).
+*
+* Throws `TxRejectedError`, `TxTimeoutError`, or `TxSignerRefusedError` from
+* `@secondlayer/stacks/errors` on failure.
+*
+* Must be called inside a workflow handler (directly or inside `step.run`).
+* Calls outside a runtime-bound context throw immediately.
+*/
+interface BroadcastOptions {
+	/** Name of a signer declared in `WorkflowDefinition.signers`. */
+	signer: string;
+	/**
+	* If `true`, wait for the tx to be confirmed on-chain before returning.
+	* Sprint 4 ships this flag as a no-op — Sprint 5 adds subgraph-backed
+	* confirmation polling.
+	*/
+	awaitConfirmation?: boolean;
+	/** Minimum confirmations before returning. Only meaningful when `awaitConfirmation: true`. */
+	minConfirmations?: number;
+	/**
+	* Hard cap on micro-STX that can be spent. Required when the tx amount is
+	* derived from an AI step (the deploy-time AST check enforces this).
+	*/
+	maxMicroStx?: bigint;
+	/** Hard cap on fee in micro-STX. */
+	maxFee?: bigint;
+}
+interface BroadcastResult {
+	txId: string;
+	/** `false` for Sprint 4; `true` once `awaitConfirmation` lands in Sprint 5. */
+	confirmed: boolean;
+}
+/**
+* Runtime contract implemented by `@secondlayer/workflow-runner`. The stacks
+* package is a pure library — it holds no keys, no DB, and no network —
+* so actual broadcasting is delegated to whatever runtime bound the context.
+*/
+interface BroadcastRuntime {
+	broadcast(intent: TxIntent, opts: BroadcastOptions): Promise<BroadcastResult>;
+}
+/**
+* Per-run `AsyncLocalStorage` binding. The runner calls
+* `broadcastContext.run(runtime, async () => handler(ctx))` so concurrent
+* workflow runs see isolated runtime bindings — no module-level global state
+* is mutated.
+*/
+declare const broadcastContext: AsyncLocalStorage<BroadcastRuntime>;
+declare function broadcast(intent: TxIntent, opts: BroadcastOptions): Promise<BroadcastResult>;
+/**
+* Structured error classes thrown by `broadcast()` and the workflow runner's
+* broadcast step. The runner's retry policy consults `reason` (for
+* `TxRejectedError`) to decide whether to re-attempt — abort-by-post-condition
+* is non-retryable, timeouts retry with a fee bump, etc.
+*/
+type TxRejectionReason = "abort_by_post_condition" | "abort_by_response" | "runtime_error" | "out_of_gas" | "nonce_conflict" | "signature_invalid" | "unknown";
+/**
+* Thrown when a transaction submitted to the Stacks node is rejected
+* (mempool or on-chain). Each `reason` maps to different retry semantics.
+*/
+declare class TxRejectedError extends Error {
+	readonly reason: TxRejectionReason;
+	readonly txId?: string;
+	readonly name = "TxRejectedError";
+	constructor(message: string, reason: TxRejectionReason, txId?: string);
+	/**
+	* Heuristic: is retrying the same tx likely to succeed?
+	* `abort_by_post_condition` / `abort_by_response` reflect on-chain state
+	* or explicit rejection — same tx will fail again.
+	*/
+	get isRetryable(): boolean;
+}
+/**
+* Thrown when a broadcast was submitted (mempool accepted) but never mined
+* within the configured `confirmationTimeout`. Retryable with fee bump.
+*/
+declare class TxTimeoutError extends Error {
+	readonly txId: string;
+	readonly timeoutMs: number;
+	readonly name = "TxTimeoutError";
+	readonly isRetryable: true;
+	constructor(message: string, txId: string, timeoutMs: number);
+}
+/**
+* Thrown when the remote signer refused to sign (policy denied, quota hit,
+* bad request). Non-retryable — customer policy won't change on retry.
+*/
+declare class TxSignerRefusedError extends Error {
+	readonly signerName: string;
+	readonly reason: string;
+	readonly name = "TxSignerRefusedError";
+	readonly isRetryable: false;
+	constructor(message: string, signerName: string, reason: string);
+}
+/** Account derived from a local private key (mnemonic or raw key). */
+type LocalAccount = {
+	type: "local"
+	address: string
+	/** Compressed public key (hex) */
+	publicKey: string
+	/** Raw ECDSA sign over a hash */
+	sign(hash: Uint8Array): Uint8Array
+	/** Sign a structured message (SIP-018) */
+	signMessage(message: string | Uint8Array): string
+};
+/** Account with a user-provided signing function (sync or async). */
+type CustomAccount = {
+	type: "custom"
+	address: string
+	publicKey: string
+	sign(hash: Uint8Array): Promise<Uint8Array> | Uint8Array
+};
+/** Browser wallet provider interface (e.g. Leather, Xverse). */
+type StacksProvider = {
+	request(method: string, params?: any): Promise<any>
+};
+/** Account backed by a browser wallet {@link StacksProvider}. */
+type ProviderAccount = {
+	type: "provider"
+	address: string
+	publicKey: string
+	provider: StacksProvider
+};
 /** Full chain descriptor used by clients and transports for network-aware operations. */
 type StacksChain = {
 	/** Chain ID (e.g. 0x00000001 for mainnet) */
@@ -68,35 +244,6 @@ type Transport = {
 type TransportFactory = (params?: {
 	chain?: StacksChain
 }) => Transport;
-/** Account derived from a local private key (mnemonic or raw key). */
-type LocalAccount = {
-	type: "local"
-	address: string
-	/** Compressed public key (hex) */
-	publicKey: string
-	/** Raw ECDSA sign over a hash */
-	sign(hash: Uint8Array): Uint8Array
-	/** Sign a structured message (SIP-018) */
-	signMessage(message: string | Uint8Array): string
-};
-/** Account with a user-provided signing function (sync or async). */
-type CustomAccount = {
-	type: "custom"
-	address: string
-	publicKey: string
-	sign(hash: Uint8Array): Promise<Uint8Array> | Uint8Array
-};
-/** Browser wallet provider interface (e.g. Leather, Xverse). */
-type StacksProvider = {
-	request(method: string, params?: any): Promise<any>
-};
-/** Account backed by a browser wallet {@link StacksProvider}. */
-type ProviderAccount = {
-	type: "provider"
-	address: string
-	publicKey: string
-	provider: StacksProvider
-};
 /** Union of all supported account types (local key, custom signer, or browser provider). */
 type Account = LocalAccount | CustomAccount | ProviderAccount;
 /**
@@ -127,25 +274,6 @@ type WalletClient<TExtended extends Record<string, unknown> = Record<string, unk
 * Use `.extend()` to compose action decorators (public, wallet, multisig).
 */
 declare function createClient<TExtended extends Record<string, unknown> = Record<string, unknown>>(config: ClientConfig): Client<TExtended>;
-type GetNonceParams = {
-	address: string
-};
-type GetBalanceParams = {
-	address: string
-};
-type GetAccountInfoParams = {
-	address: string
-};
-type AccountInfo = {
-	balance: bigint
-	nonce: bigint
-	balanceProof: string
-	nonceProof: string
-};
-type GetBlockParams = {
-	height?: number
-	hash?: string
-};
 type IntCV = {
 	readonly type: "int"
 	readonly value: bigint
@@ -170,15 +298,15 @@ type NoneCV = {
 };
 type SomeCV = {
 	readonly type: "some"
-	readonly value: ClarityValue
+	readonly value: ClarityValue2
 };
 type ResponseOkCV = {
 	readonly type: "ok"
-	readonly value: ClarityValue
+	readonly value: ClarityValue2
 };
 type ResponseErrorCV = {
 	readonly type: "err"
-	readonly value: ClarityValue
+	readonly value: ClarityValue2
 };
 type StandardPrincipalCV = {
 	readonly type: "address"
@@ -190,10 +318,10 @@ type ContractPrincipalCV = {
 };
 type ListCV = {
 	type: "list"
-	value: ClarityValue[]
+	value: ClarityValue2[]
 };
 type TupleData = {
-	[key: string]: ClarityValue
+	[key: string]: ClarityValue2
 };
 type TupleCV = {
 	type: "tuple"
@@ -207,21 +335,7 @@ type StringUtf8CV = {
 	readonly type: "utf8"
 	readonly value: string
 };
-type ClarityValue = IntCV | UIntCV | BooleanCV | BufferCV | NoneCV | SomeCV | ResponseOkCV | ResponseErrorCV | StandardPrincipalCV | ContractPrincipalCV | ListCV | TupleCV | StringAsciiCV | StringUtf8CV;
-type ReadContractParams = {
-	contract: string
-	functionName: string
-	args?: ClarityValue[]
-	sender?: string
-};
-type GetContractAbiParams = {
-	contract: string
-};
-type GetMapEntryParams = {
-	contract: string
-	mapName: string
-	key: ClarityValue
-};
+type ClarityValue2 = IntCV | UIntCV | BooleanCV | BufferCV | NoneCV | SomeCV | ResponseOkCV | ResponseErrorCV | StandardPrincipalCV | ContractPrincipalCV | ListCV | TupleCV | StringAsciiCV | StringUtf8CV;
 declare const AuthType: {
 	readonly Standard: 0x04
 	readonly Sponsored: 0x05
@@ -243,6 +357,8 @@ declare const ClarityVersion: {
 	readonly Clarity1: 1
 	readonly Clarity2: 2
 	readonly Clarity3: 3
+	readonly Clarity4: 4
+	readonly Clarity5: 5
 };
 type ClarityVersion = (typeof ClarityVersion)[keyof typeof ClarityVersion];
 declare const AnchorMode: {
@@ -273,11 +389,16 @@ type PubKeyEncoding = (typeof PubKeyEncoding)[keyof typeof PubKeyEncoding];
 declare const TenureChangeCause: {
 	readonly BlockFound: 0x00
 	readonly Extended: 0x01
+	readonly ExtendedRuntime: 0x02
+	readonly ExtendedReadCount: 0x03
+	readonly ExtendedReadLength: 0x04
+	readonly ExtendedWriteCount: 0x05
+	readonly ExtendedWriteLength: 0x06
 };
 type TenureChangeCause = (typeof TenureChangeCause)[keyof typeof TenureChangeCause];
 type TokenTransferPayload = {
 	payloadType: typeof PayloadType.TokenTransfer
-	recipient: ClarityValue
+	recipient: ClarityValue2
 	amount: bigint
 	memo: string
 };
@@ -286,7 +407,7 @@ type ContractCallPayload = {
 	contractAddress: string
 	contractName: string
 	functionName: string
-	functionArgs: ClarityValue[]
+	functionArgs: ClarityValue2[]
 };
 type SmartContractPayload = {
 	payloadType: typeof PayloadType.SmartContract | typeof PayloadType.VersionedSmartContract
@@ -301,7 +422,7 @@ type CoinbasePayload = {
 type CoinbaseToAltRecipientPayload = {
 	payloadType: typeof PayloadType.CoinbaseToAltRecipient
 	coinbaseBuffer: string
-	recipient: ClarityValue
+	recipient: ClarityValue2
 };
 type PoisonMicroblockPayload = {
 	payloadType: typeof PayloadType.PoisonMicroblock
@@ -321,7 +442,7 @@ type TenureChangePayload = {
 type NakamotoCoinbasePayload = {
 	payloadType: typeof PayloadType.NakamotoCoinbase
 	coinbaseBuffer: string
-	recipient: ClarityValue | null
+	recipient: ClarityValue2 | null
 	vrfProof: string
 };
 type TransactionPayload = TokenTransferPayload | ContractCallPayload | SmartContractPayload | CoinbasePayload | CoinbaseToAltRecipientPayload | PoisonMicroblockPayload | TenureChangePayload | NakamotoCoinbasePayload;
@@ -386,7 +507,7 @@ type NftPostConditionWire = {
 	principal: PostConditionPrincipalWire
 	asset: AssetInfoWire
 	conditionCode: number
-	assetId: ClarityValue
+	assetId: ClarityValue2
 };
 type PostConditionPrincipalWire = {
 	type: "origin"
@@ -410,10 +531,37 @@ type FeeEstimation = {
 	feeRate: number
 	fee: number
 };
+type GetAccountInfoParams = {
+	address: string
+};
+type AccountInfo = {
+	balance: bigint
+	nonce: bigint
+	balanceProof: string
+	nonceProof: string
+};
+type GetBalanceParams = {
+	address: string
+};
+type GetBlockParams = {
+	height?: number
+	hash?: string
+};
+type GetContractAbiParams = {
+	contract: string
+};
+type GetMapEntryParams = {
+	contract: string
+	mapName: string
+	key: ClarityValue2
+};
+type GetNonceParams = {
+	address: string
+};
 type MulticallCall = {
 	contract: string
 	functionName: string
-	args?: ClarityValue[]
+	args?: ClarityValue2[]
 	sender?: string
 };
 type MulticallParams<TAllowFailure extends boolean = true> = {
@@ -422,13 +570,19 @@ type MulticallParams<TAllowFailure extends boolean = true> = {
 };
 type MulticallSuccessResult = {
 	status: "success"
-	result: ClarityValue
+	result: ClarityValue2
 };
 type MulticallFailureResult = {
 	status: "failure"
 	error: Error
 };
-type MulticallResult<T extends boolean> = T extends true ? (MulticallSuccessResult | MulticallFailureResult)[] : ClarityValue[];
+type MulticallResult<T extends boolean> = T extends true ? (MulticallSuccessResult | MulticallFailureResult)[] : ClarityValue2[];
+type ReadContractParams = {
+	contract: string
+	functionName: string
+	args?: ClarityValue2[]
+	sender?: string
+};
 declare class BaseError extends Error {
 	name: string;
 	shortMessage: string;
@@ -456,13 +610,13 @@ declare class SimulationError extends BaseError {
 type SimulateCallParams = {
 	contract: string
 	functionName: string
-	args?: ClarityValue[]
+	args?: ClarityValue2[]
 	sender?: string
 	tip?: string
 };
 type SimulateCallSuccess = {
 	success: true
-	result: ClarityValue
+	result: ClarityValue2
 };
 type SimulateCallFailure = {
 	success: false
@@ -630,9 +784,9 @@ type PublicActions = {
 	getAccountInfo: (params: GetAccountInfoParams) => Promise<AccountInfo>
 	getBlock: (params: GetBlockParams) => Promise<any>
 	getBlockHeight: () => Promise<number>
-	readContract: (params: ReadContractParams) => Promise<ClarityValue>
+	readContract: (params: ReadContractParams) => Promise<ClarityValue2>
 	getContractAbi: (params: GetContractAbiParams) => Promise<any>
-	getMapEntry: (params: GetMapEntryParams) => Promise<ClarityValue>
+	getMapEntry: (params: GetMapEntryParams) => Promise<ClarityValue2>
 	estimateFee: (params: EstimateFeeParams) => Promise<FeeEstimation[]>
 	multicall: <T extends boolean = true>(params: MulticallParams<T>) => Promise<MulticallResult<T>>
 	simulateCall: (params: SimulateCallParams) => Promise<SimulateCallResult>
@@ -653,18 +807,6 @@ type PublicClientConfig = Omit<ClientConfig, "account">;
 * Use for queries, contract reads, and event subscriptions.
 */
 declare function createPublicClient(config: PublicClientConfig): Client<PublicActions> & PublicActions;
-type SendTransactionParams = {
-	transaction: StacksTransaction
-	attachment?: Uint8Array | string
-};
-type SendTransactionResult = {
-	txid: string
-};
-type SignTransactionParams = {
-	transaction: StacksTransaction
-	/** Public keys for multi-sig signing (auto-detected from _multisig metadata if omitted) */
-	signers?: string[]
-};
 type FungibleComparator = "eq" | "gt" | "gte" | "lt" | "lte";
 type NonFungibleComparator = "sent" | "not-sent";
 type StxPostCondition = {
@@ -685,27 +827,18 @@ type NftPostCondition = {
 	address: string
 	condition: NonFungibleComparator
 	asset: string
-	assetId: ClarityValue
+	assetId: ClarityValue2
 };
-type PostCondition = StxPostCondition | FtPostCondition | NftPostCondition;
+type PostCondition2 = StxPostCondition | FtPostCondition | NftPostCondition;
 type IntegerType = number | string | bigint | Uint8Array;
-type TransferStxParams = {
-	to: string
-	amount: IntegerType
-	memo?: string
-	fee?: IntegerType
-	nonce?: IntegerType
-	postConditionMode?: "allow" | "deny"
-	postConditions?: PostCondition[]
-};
 type CallContractParams = {
 	contract: string
 	functionName: string
-	functionArgs?: ClarityValue[]
+	functionArgs?: ClarityValue2[]
 	fee?: IntegerType
 	nonce?: IntegerType
 	postConditionMode?: "allow" | "deny"
-	postConditions?: PostCondition[]
+	postConditions?: PostCondition2[]
 };
 type DeployContractParams = {
 	contractName: string
@@ -714,21 +847,42 @@ type DeployContractParams = {
 	fee?: IntegerType
 	nonce?: IntegerType
 	postConditionMode?: "allow" | "deny"
-	postConditions?: PostCondition[]
+	postConditions?: PostCondition2[]
+};
+type SendTransactionParams = {
+	transaction: StacksTransaction
+	attachment?: Uint8Array | string
+};
+type SendTransactionResult = {
+	txid: string
 };
 type SignMessageParams = {
-	message: string | ClarityValue
+	message: string | ClarityValue2
 	domain?: {
 		name: string
 		version: string
 		chainId: number
 	}
 };
+type SignTransactionParams = {
+	transaction: StacksTransaction
+	/** Public keys for multi-sig signing (auto-detected from _multisig metadata if omitted) */
+	signers?: string[]
+};
 type SponsorTransactionParams = {
 	transaction: StacksTransaction
 	fee?: IntegerType
 	nonce?: IntegerType
 };
+type TransferStxParams = {
+	to: string
+	amount: IntegerType
+	memo?: string
+	fee?: IntegerType
+	nonce?: IntegerType
+	postConditionMode?: "allow" | "deny"
+	postConditions?: PostCondition2[]
+};
 /** Signing actions: send transactions, transfer STX, call/deploy contracts, sign messages. */
 type WalletActions = {
 	sendTransaction: (params: SendTransactionParams) => Promise<SendTransactionResult>
@@ -758,16 +912,16 @@ type MultiSigTransferStxParams = {
 	fee?: IntegerType
 	nonce?: IntegerType
 	postConditionMode?: "allow" | "deny"
-	postConditions?: PostCondition[]
+	postConditions?: PostCondition2[]
 };
 type MultiSigCallContractParams = {
 	contract: string
 	functionName: string
-	functionArgs?: ClarityValue[]
+	functionArgs?: ClarityValue2[]
 	fee?: IntegerType
 	nonce?: IntegerType
 	postConditionMode?: "allow" | "deny"
-	postConditions?: PostCondition[]
+	postConditions?: PostCondition2[]
 };
 type MultiSigDeployContractParams = {
 	contractName: string
@@ -776,7 +930,7 @@ type MultiSigDeployContractParams = {
 	fee?: IntegerType
 	nonce?: IntegerType
 	postConditionMode?: "allow" | "deny"
-	postConditions?: PostCondition[]
+	postConditions?: PostCondition2[]
 };
 type MultiSigSendTransactionParams = {
 	transaction: StacksTransaction
@@ -885,4 +1039,36 @@ declare function isAddressEqual(a: string, b: string): boolean;
 * Validates both parts; returns `deployer.contractName`.
 */
 declare function getContractAddress(deployer: string, contractName: string): string;
-export { webSocket, walletActions, testnet, publicActions, providerToAccount, parseStx, multisigActions, mocknet, mainnet, isValidAddress, isAddressEqual, http, getContractAddress, formatStx, fallback, devnet, defineChain, custom, createWalletClient, createPublicClient, createMultiSigClient, createClient, ZERO_ADDRESS, WebSocketTransportConfig, WebSocketTransport, WalletClientConfig, WalletClient, WalletActions, TransportFactory, TransportConfig, Transport, TESTNET_ZERO_ADDRESS, Subscription, StacksProvider, StacksChain, RequestOptions, RequestFn, PublicClientConfig, PublicClient, PublicActions, ProviderAccount, MultiSigClientConfig, MultiSigClient, MultiSigActions, MICROSTX_PER_STX, LocalAccount, CustomAccount, ClientConfig, Client, AddressVersion, Account };
+declare class TransactionError extends BaseError {
+	name: string;
+}
+declare class BroadcastError extends BaseError {
+	name: string;
+	txid?: string;
+	reason?: string;
+	constructor(message: string, options?: {
+		cause?: Error
+		txid?: string
+		reason?: string
+	});
+}
+declare class SerializationError extends BaseError {
+	name: string;
+}
+declare class SigningError extends BaseError {
+	name: string;
+}
+declare class ContractCallError extends BaseError {
+	name: string;
+}
+declare class ReadOnlyCallError extends BaseError {
+	name: string;
+}
+declare class WebSocketError extends BaseError {
+	name: string;
+	constructor(message: string, options?: {
+		cause?: Error
+		details?: string
+	});
+}
+export { webSocket, walletActions, tx, testnet, publicActions, providerToAccount, parseStx, multisigActions, mocknet, mainnet, isValidAddress, isAddressEqual, http, getContractAddress, formatStx, fallback, devnet, defineChain, custom, createWalletClient, createPublicClient, createMultiSigClient, createClient, broadcastContext, broadcast, ZERO_ADDRESS, WebSocketTransportConfig, WebSocketTransport, WebSocketError, WalletClientConfig, WalletClient, WalletActions, TxTimeoutError, TxSignerRefusedError, TxRejectionReason, TxRejectedError, TxIntent, TransportFactory, TransportConfig, Transport, TransferIntent, TransactionError, TESTNET_ZERO_ADDRESS, Subscription, StacksProvider, StacksChain, SimulationError, SigningError, SerializationError, RequestOptions, RequestFn, ReadOnlyCallError, PublicClientConfig, PublicClient, PublicActions, ProviderAccount, MultiSigClientConfig, MultiSigClient, MultiSigActions, MultiSendIntent, MICROSTX_PER_STX, LocalAccount, DeployIntent, CustomAccount, ContractCallIntent, ContractCallError, ClientConfig, Client, BroadcastRuntime, BroadcastResult, BroadcastOptions, BroadcastError, BaseError, AddressVersion, Account };