Implementation

Learn how to add post-conditions to protect your Stacks transactions.

Post-conditions are a powerful security feature in Stacks that protect users from unexpected transaction outcomes. This tutorial will walk you through implementing post-conditions in your applications to ensure transactions behave exactly as users expect.

What you'll learn

• Construct post-conditions using the Pc helper API
• Add post-conditions to different transaction types
• Configure post-condition modes for transaction security
• Implement post-conditions for STX, fungible tokens, and NFTs
• Handle semi-fungible tokens (SFTs) with post-conditions
• Use Originator mode to protect only the transaction sender's assets (SIP-040)
• Use the MAY SEND token condition to optionally cover an NFT/SFT transfer (SIP-040)

Constructing post-conditions

The Pc helper in Stacks.js provides a fluent, BDD-inspired API for constructing post-conditions. Start with Pc.principal() to specify which address will be verified, then chain methods to define the condition.

import { Pc } from '@stacks/transactions';

// Basic structure of a post-condition
const postCondition = Pc
  .principal('STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6')
  .willSendEq(1000)
  .ustx();

The Pc helper uses method chaining for intuitive condition building. Your IDE will provide auto-completion for available methods at each step.

---

Available transfer methods

Post-conditions support different comparison operators and asset types. Choose the appropriate method based on your security requirements.

STX and fungible token methods

// Exact amount
Pc.principal(address).willSendEq(1000).ustx();

// Greater than or equal
Pc.principal(address).willSendGte(500).ustx();

// Less than
Pc.principal(address).willSendLt(2000).ustx();

Comparison methods available:

• .willSendEq(amount) - Exactly equal to amount
• .willSendGte(amount) - Greater than or equal to amount
• .willSendGt(amount) - Greater than amount
• .willSendLte(amount) - Less than or equal to amount
• .willSendLt(amount) - Less than amount

Asset type methods

// STX transfers
.ustx()

// Fungible token transfers
.ft(contractAddress, tokenName)

// NFT transfers
.nft(assetIdentifier, tokenId)

NFT-specific methods

// Ensure NFT is sent
Pc.principal(address).willSendAsset().nft(...);

// Ensure NFT is NOT sent
Pc.principal(address).willNotSendAsset().nft(...);

// Ensure NFT MAY be sent (covers the asset in Deny/Originator allowlist
// without requiring it to actually move). SIP-040, epoch 3.4+.
Pc.principal(address).willMaybeSendAsset().nft(...);

Use willMaybeSendAsset() when an NFT/SFT transfer is conditional inside the contract and you want the transaction to succeed whether or not it moves. Available from Stacks epoch 3.4 (SIP-040).

---

Setting the post-condition mode

The post-condition mode determines how the Stacks protocol handles asset transfers not explicitly covered by your post-conditions. This is a critical security setting.

import { PostConditionMode, makeContractCall } from '@stacks/transactions';

const tx = await makeContractCall({
  // ... other transaction properties
  postConditionMode: PostConditionMode.Deny, // Recommended default
  postConditions: [
    // your post-conditions here
  ],
});

import { Pc, PostConditionMode, makeContractCall } from '@stacks/transactions';

// Originator mode: protect only the sender's assets in a multi-hop contract call
const tx = await makeContractCall({
  // ... other transaction properties
  postConditionMode: PostConditionMode.Originator,
  postConditions: [
    // Only constrain the origin account's outflows
    Pc.principal(senderAddress).willSendLte(1_000_000).ustx(),
    Pc.principal(senderAddress).willSendLte(50_000_000)
      .ft('SP3D6PV2ACBPEKYJTCMH7HEN02KP87QSP8KTEH335.usdcx', 'usdcx'),
  ],
});

Mode options:

• PostConditionMode.Deny (default): Transaction fails if any unspecified transfers occur
• PostConditionMode.Originator: Transaction fails only if unspecified transfers originate from the transaction's origin account; transfers between other principals are allowed (SIP-040, epoch 3.4+, live since March 2026)
• PostConditionMode.Allow: Transaction allows transfers beyond specified post-conditions

Originator mode is intended for DeFi-style contract calls where intermediate asset routing between contracts is unpredictable. It applies Deny-style protection to the origin account's assets while permitting movements between other principals.

---

Common implementation patterns

STX transfer post-conditions

Protect STX transfers by specifying exact amounts or ranges.

import { Pc, makeSTXTokenTransfer } from '@stacks/transactions';

// Exact amount post-condition
const exactAmountCondition = Pc
  .principal('STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6')
  .willSendEq(1000)
  .ustx();

// Use in a transaction
const tx = await makeSTXTokenTransfer({
  recipient: 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM',
  amount: 1000,
  postConditions: [exactAmountCondition],
  postConditionMode: PostConditionMode.Deny,
  // ... other properties
});

Fungible token post-conditions

Ensure fungible tokens are transferred as expected in contract calls.

import { Pc, makeContractCall } from '@stacks/transactions';

// Minimum amount condition
const ftCondition = Pc
  .principal('STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6')
  .willSendGte(500)
  .ft('STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6.token-ft', 'token');

// Use in a contract call
const tx = await makeContractCall({
  contractAddress: 'STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6',
  contractName: 'token-transfer',
  functionName: 'transfer',
  functionArgs: [
    // ... function arguments
  ],
  postConditions: [ftCondition],
  // ... other properties
});

NFT transfer post-conditions

Control NFT ownership changes with specific post-conditions.

import { Pc, Cl } from '@stacks/transactions';

// Ensure NFT is sent
const sendNftCondition = Pc
  .principal('STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6')
  .willSendAsset()
  .nft('STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6.nft-contract::nft-name', Cl.uint(1));

// Ensure NFT is NOT sent (protection against unwanted transfers)
const keepNftCondition = Pc
  .principal('STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6')
  .willNotSendAsset()
  .nft('STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6.nft-contract::nft-name', Cl.uint(1));

Use willNotSendAsset() to protect valuable NFTs from being transferred unexpectedly.

Semi-fungible token (SFT) post-conditions

SFTs require special handling as they have both fungible and non-fungible properties.

import { Cl, Pc } from '@stacks/transactions';

// SFT as NFT (specific token ID)
const sftNftCondition = Pc
  .principal('STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6')
  .willSendAsset()
  .nft(
    'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.sft-contract::sft-id',
    Cl.tuple({
      'token-id': Cl.uint(1),
      owner: Cl.principal('STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6')
    })
  );

// SFT as FT (amount-based)
const sftFtCondition = Pc
  .principal('STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6')
  .willSendEq(500)
  .ft('ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.sft-contract', 'sft-token');

Multi-bin withdrawals (Bitflow DLMM, concentrated-liquidity pools) typically produce one willMaybeSendAsset() post-condition per affected bin. The position SFT for each bin may be burned (transferred to the contract) or kept depending on the remaining liquidity after the call. Pairing each per-bin condition with willSendLte conditions on the underlying FTs gives the signer a precise upper bound on what can leave their account while allowing the contract to skip burns for bins that retain liquidity.

// SFT-as-NFT with MAY SEND — for contracts that may or may not transfer
// a specific token-id depending on runtime state (e.g. DLMM/CLMM pools
// where a bin's position SFT is burned only if its liquidity reaches zero).
const sftBinCondition = Pc
  .principal(senderAddress)
  .willMaybeSendAsset()
  .nft(
    'SP000...pool.dlmm-position::position',
    Cl.tuple({
      'pool-id': Cl.uint(1),
      'bin-id': Cl.uint(8421),
      owner: Cl.principal(senderAddress),
    })
  );

Originator-mode post-conditions for DeFi (SIP-040)

When calling a contract that routes assets through several intermediate contracts, listing every hop in Deny mode is brittle. Originator mode restricts only the sender's own outflows and allows asset movement between other principals.

import { Pc, PostConditionMode, makeContractCall } from '@stacks/transactions';

const tx = await makeContractCall({
  contractAddress: 'SP000...router',
  contractName: 'multi-hop-swap',
  functionName: 'swap',
  functionArgs: [ /* ... */ ],
  postConditionMode: PostConditionMode.Originator,
  postConditions: [
    // Cap STX leaving the sender
    Pc.origin().willSendLte(1_000_000).ustx(),
    // Cap USDCx leaving the sender
    Pc.origin().willSendLte(100_000_000)
      .ft('SP3D6PV2ACBPEKYJTCMH7HEN02KP87QSP8KTEH335.usdcx', 'usdcx'),
  ],
});

Pc.origin() is a convenience that binds the post-condition to the transaction's origin account (the signer of the standard authorization structure, not tx-sender, and unaffected by as-contract?).

Multiple post-conditions

Complex transactions often require multiple post-conditions to fully protect all asset transfers.

const tx = await makeContractCall({
  // ... transaction properties
  postConditions: [
    // Sender must send exactly 1000 uSTX
    Pc.principal(senderAddress).willSendEq(1000).ustx(),

    // Contract must send at least 100 tokens to user
    Pc.principal(contractAddress).willSendGte(100)
      .ft(contractAddress + '.my-token', 'my-token'),

    // User must not lose their NFT
    Pc.principal(senderAddress).willNotSendAsset()
      .nft(nftContract + '::my-nft', Cl.uint(1)),
  ],
  postConditionMode: PostConditionMode.Deny,
});