@secondlayer/stacks 2.4.0 → 2.5.1

package/dist/src/x402/index.d.cts

@@ -0,0 +1,424 @@
+/** Full chain descriptor used by clients and transports for network-aware operations. */
+type StacksChain = {
+	/** Chain ID (e.g. 0x00000001 for mainnet) */
+	id: number
+	/** Human-readable name */
+	name: string
+	/** Network type */
+	network: "mainnet" | "testnet"
+	/** Transaction version byte for serialization */
+	transactionVersion: number
+	/** Peer network ID for P2P broadcasting */
+	peerNetworkId: number
+	/** Address version bytes */
+	addressVersion: {
+		singleSig: number
+		multiSig: number
+	}
+	/** Magic bytes for network identification */
+	magicBytes: string
+	/** Boot address (system contracts deployer) */
+	bootAddress: string
+	/** Native currency info */
+	nativeCurrency: {
+		name: string
+		symbol: string
+		decimals: number
+	}
+	/** Default RPC URLs */
+	rpcUrls: {
+		default: {
+			http: string[]
+			ws?: string[]
+		}
+	}
+	/** Block explorer URLs */
+	blockExplorers?: {
+		default: {
+			name: string
+			url: string
+		}
+	}
+};
+type IntCV = {
+	readonly type: "int"
+	readonly value: bigint
+};
+type UIntCV = {
+	readonly type: "uint"
+	readonly value: bigint
+};
+type BooleanCV = TrueCV | FalseCV;
+type TrueCV = {
+	readonly type: "true"
+};
+type FalseCV = {
+	readonly type: "false"
+};
+type BufferCV = {
+	readonly type: "buffer"
+	readonly value: string
+};
+type NoneCV = {
+	readonly type: "none"
+};
+type SomeCV = {
+	readonly type: "some"
+	readonly value: ClarityValue
+};
+type ResponseOkCV = {
+	readonly type: "ok"
+	readonly value: ClarityValue
+};
+type ResponseErrorCV = {
+	readonly type: "err"
+	readonly value: ClarityValue
+};
+type StandardPrincipalCV = {
+	readonly type: "address"
+	readonly value: string
+};
+type ContractPrincipalCV = {
+	readonly type: "contract"
+	readonly value: string
+};
+type ListCV = {
+	type: "list"
+	value: ClarityValue[]
+};
+type TupleData = {
+	[key: string]: ClarityValue
+};
+type TupleCV = {
+	type: "tuple"
+	value: TupleData
+};
+type StringAsciiCV = {
+	readonly type: "ascii"
+	readonly value: string
+};
+type StringUtf8CV = {
+	readonly type: "utf8"
+	readonly value: string
+};
+type ClarityValue = IntCV | UIntCV | BooleanCV | BufferCV | NoneCV | SomeCV | ResponseOkCV | ResponseErrorCV | StandardPrincipalCV | ContractPrincipalCV | ListCV | TupleCV | StringAsciiCV | StringUtf8CV;
+declare const AuthType: {
+	readonly Standard: 0x04
+	readonly Sponsored: 0x05
+};
+type AuthType = (typeof AuthType)[keyof typeof AuthType];
+declare const PayloadType: {
+	readonly TokenTransfer: 0x00
+	readonly SmartContract: 0x01
+	readonly ContractCall: 0x02
+	readonly PoisonMicroblock: 0x03
+	readonly Coinbase: 0x04
+	readonly CoinbaseToAltRecipient: 0x05
+	readonly VersionedSmartContract: 0x06
+	readonly TenureChange: 0x07
+	readonly NakamotoCoinbase: 0x08
+};
+type PayloadType = (typeof PayloadType)[keyof typeof PayloadType];
+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: {
+	readonly OnChainOnly: 0x01
+	readonly OffChainOnly: 0x02
+	readonly Any: 0x03
+};
+type AnchorMode = (typeof AnchorMode)[keyof typeof AnchorMode];
+declare const PostConditionModeWire: {
+	readonly Allow: 0x01
+	readonly Deny: 0x02
+};
+type PostConditionModeWire = (typeof PostConditionModeWire)[keyof typeof PostConditionModeWire];
+declare const AddressHashMode: {
+	readonly P2PKH: 0x00
+	readonly P2SH: 0x01
+	readonly P2WPKH: 0x02
+	readonly P2WSH: 0x03
+	readonly P2SH_NonSequential: 0x05
+	readonly P2WSH_P2SH_NonSequential: 0x07
+};
+type AddressHashMode = (typeof AddressHashMode)[keyof typeof AddressHashMode];
+declare const PubKeyEncoding: {
+	readonly Compressed: 0x00
+	readonly Uncompressed: 0x01
+};
+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
+	amount: bigint
+	memo: string
+};
+type ContractCallPayload = {
+	payloadType: typeof PayloadType.ContractCall
+	contractAddress: string
+	contractName: string
+	functionName: string
+	functionArgs: ClarityValue[]
+};
+type SmartContractPayload = {
+	payloadType: typeof PayloadType.SmartContract | typeof PayloadType.VersionedSmartContract
+	clarityVersion?: ClarityVersion
+	contractName: string
+	codeBody: string
+};
+type CoinbasePayload = {
+	payloadType: typeof PayloadType.Coinbase
+	coinbaseBuffer: string
+};
+type CoinbaseToAltRecipientPayload = {
+	payloadType: typeof PayloadType.CoinbaseToAltRecipient
+	coinbaseBuffer: string
+	recipient: ClarityValue
+};
+type PoisonMicroblockPayload = {
+	payloadType: typeof PayloadType.PoisonMicroblock
+	header1: string
+	header2: string
+};
+type TenureChangePayload = {
+	payloadType: typeof PayloadType.TenureChange
+	tenureConsensusHash: string
+	prevTenureConsensusHash: string
+	burnViewConsensusHash: string
+	previousTenureEnd: string
+	previousTenureBlocks: number
+	cause: TenureChangeCause
+	pubkeyHash: string
+};
+type NakamotoCoinbasePayload = {
+	payloadType: typeof PayloadType.NakamotoCoinbase
+	coinbaseBuffer: string
+	recipient: ClarityValue | null
+	vrfProof: string
+};
+type TransactionPayload = TokenTransferPayload | ContractCallPayload | SmartContractPayload | CoinbasePayload | CoinbaseToAltRecipientPayload | PoisonMicroblockPayload | TenureChangePayload | NakamotoCoinbasePayload;
+type SingleSigSpendingCondition = {
+	hashMode: typeof AddressHashMode.P2PKH | typeof AddressHashMode.P2WPKH
+	signer: string
+	nonce: bigint
+	fee: bigint
+	keyEncoding: PubKeyEncoding
+	signature: string
+};
+type TransactionAuthField = {
+	pubKeyEncoding: PubKeyEncoding
+	type: "publicKey" | "signature"
+	data: string
+};
+type MultiSigHashMode = typeof AddressHashMode.P2SH | typeof AddressHashMode.P2WSH | typeof AddressHashMode.P2SH_NonSequential | typeof AddressHashMode.P2WSH_P2SH_NonSequential;
+type MultiSigSpendingCondition = {
+	hashMode: MultiSigHashMode
+	signer: string
+	nonce: bigint
+	fee: bigint
+	fields: TransactionAuthField[]
+	signaturesRequired: number
+};
+type SpendingCondition = SingleSigSpendingCondition | MultiSigSpendingCondition;
+type StandardAuthorization = {
+	authType: typeof AuthType.Standard
+	spendingCondition: SpendingCondition
+};
+type SponsoredAuthorization = {
+	authType: typeof AuthType.Sponsored
+	spendingCondition: SpendingCondition
+	sponsorSpendingCondition: SpendingCondition
+};
+type Authorization = StandardAuthorization | SponsoredAuthorization;
+type StacksTransaction = {
+	version: number
+	chainId: number
+	auth: Authorization
+	anchorMode: AnchorMode
+	postConditionMode: PostConditionModeWire
+	postConditions: PostConditionWire[]
+	payload: TransactionPayload
+};
+type PostConditionWire = StxPostConditionWire | FtPostConditionWire | NftPostConditionWire;
+type StxPostConditionWire = {
+	type: "stx"
+	principal: PostConditionPrincipalWire
+	conditionCode: number
+	amount: bigint
+};
+type FtPostConditionWire = {
+	type: "ft"
+	principal: PostConditionPrincipalWire
+	asset: AssetInfoWire
+	conditionCode: number
+	amount: bigint
+};
+type NftPostConditionWire = {
+	type: "nft"
+	principal: PostConditionPrincipalWire
+	asset: AssetInfoWire
+	conditionCode: number
+	assetId: ClarityValue
+};
+type PostConditionPrincipalWire = {
+	type: "origin"
+} | {
+	type: "standard"
+	address: string
+} | {
+	type: "contract"
+	address: string
+	contractName: string
+};
+type AssetInfoWire = {
+	address: string
+	contractName: string
+	assetName: string
+};
+type IntegerType = number | string | bigint | Uint8Array;
+/**
+* The asset an x402 payment moves. Either native STX or a SIP-010 token,
+* in which case the fully-qualified contract id and the fungible-token asset
+* name (the `::<asset-name>` suffix, e.g. `sbtc-token`) are both required —
+* the asset name is not always equal to the contract name.
+*/
+type X402Asset = {
+	kind: "stx"
+} | {
+	kind: "sip010"
+	contractId: string
+	assetName: string
+};
+type BuildExactTransferOptions = {
+	/** The asset and amount to move. */
+	asset: X402Asset
+	amount: IntegerType
+	/** Recipient principal (the resource server's `payTo`). */
+	payTo: string
+	/** Origin/payer principal — pinned by the post-condition. */
+	payer: string
+	/** Origin compressed public key (the payer signs origin-only). */
+	payerPublicKey: string
+	/** The payer account's next nonce. */
+	accountNonce: IntegerType
+	/**
+	* The x402 challenge nonce, carried in the on-chain memo so the facilitator
+	* can correlate the settled tx with the challenge. Bound to ≤ 34 bytes
+	* (UTF-8) — both the STX memo and the SIP-010 `(buff 34)` memo arg cap there.
+	*/
+	nonce: string
+	chain?: StacksChain
+};
+/**
+* Build an exact-amount, Deny-mode, post-conditioned, **sponsored** transfer
+* (origin-only, un-broadcast). The origin sets fee `0`; the facilitator's
+* sponsor fills in + pays the fee at settle time. The Deny-mode post-condition
+* asserts EXACTLY `amount` leaves `payer` to `payTo`, so settlement aborts
+* on-chain if anything differs — the "exact amount" x402 guarantee is enforced
+* by Clarity, not just by facilitator simulation.
+*/
+declare function buildExactTransfer(options: BuildExactTransferOptions): StacksTransaction;
+/** 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
+};
+/** Function that sends an HTTP request to a Stacks node API path. */
+type RequestFn = (path: string, options?: RequestOptions) => Promise<any>;
+/** Options for a transport-level HTTP request. */
+type RequestOptions = {
+	method?: "GET" | "POST" | "PUT" | "DELETE"
+	body?: unknown
+	headers?: Record<string, string>
+};
+/** Shared configuration for all transport types. */
+type TransportConfig = {
+	url?: string
+	timeout?: number
+	retryCount?: number
+	retryDelay?: number
+	fetchOptions?: RequestInit
+	apiKey?: string
+};
+/** A resolved transport instance with a bound request function. */
+type Transport = {
+	type: string
+	request: RequestFn
+	config: TransportConfig
+	destroy?: () => void
+};
+/** Union of all supported account types (local key, custom signer, or browser provider). */
+type Account = LocalAccount | CustomAccount | ProviderAccount;
+/**
+* Core client instance that holds chain context, transport, and extensible actions.
+* Created via {@link createClient}, {@link createPublicClient}, or {@link createWalletClient}.
+*/
+type Client<TExtended extends Record<string, unknown> = Record<string, unknown>> = {
+	chain?: StacksChain
+	account?: Account
+	transport: Transport
+	request: RequestFn
+	extend: <const TNew extends Record<string, unknown>>(fn: (client: Client<TExtended>) => TNew) => Client<TExtended & TNew> & TNew
+} & TExtended;
+type SponsorAndBroadcastOptions = {
+	/** Override the sponsor fee (µSTX). Defaults to a fee estimate. */
+	fee?: IntegerType
+	/** Override the sponsor account nonce. Defaults to the on-chain nonce. */
+	nonce?: IntegerType
+};
+type SponsorAndBroadcastResult = {
+	txid: string
+};
+/**
+* Take an origin-signed, sponsored transfer (hex) from the payer, sponsor-sign
+* it with `client`'s account (paying the STX fee), and broadcast it.
+*
+* The payer never holds STX: they sign origin-only with fee `0`; this fills in
+* the sponsor spending condition + fee and POSTs to `/v2/transactions`. The
+* sponsor cannot grief the payer — amount/recipient/asset are pinned by the
+* origin signature + Deny-mode post-conditions baked into the tx.
+*
+* @param client a wallet client whose `account` is the funded sponsor signer.
+* @param signedTxHex the payer's origin-signed sponsored tx, hex-serialized.
+*/
+declare function sponsorAndBroadcast(client: Client, signedTxHex: string, options?: SponsorAndBroadcastOptions): Promise<SponsorAndBroadcastResult>;
+export { sponsorAndBroadcast, buildExactTransfer, X402Asset, SponsorAndBroadcastResult, SponsorAndBroadcastOptions, BuildExactTransferOptions };