Examples

These examples showcase the power of post-conditions through multiple scenarios you might encounter as a Stacks developer.

No transfers

A simple contract function with no asset transfers specified.

On the frontend, this should be set to a postConditionMode of "deny", without needing a specific post-condition statement.

(define-public (no-transfers)
  (ok "no transfer events executed.")
)

We will specify the postConditionMode to deny. No other post-condition statements are needed. postConditions can be set to an empty array.

The user's expectation should be to deny any asset transfers.

const response = await request("stx_callContract", {
  contract: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.post-conditions",
  functionName: "no-transfers",
  network: "devnet",
  postConditions: [],
  postConditionMode: "deny"
})

User Expectation: No assets will be transferred out of their wallet.

Result: No transfers made during transaction execution. Transaction is confirmed.

Single STX transfer

A function that contains a single asset transfer of 10 STX from the tx-sender to the contract.

(define-public (single-stx-transfer)
  (stx-transfer? u10000000 tx-sender (as-contract tx-sender))
)

A StxPostCondition will be set with the origin/user address, and how much the user expects to be sending out. The postConditionMode is set to deny to prevent any other unexpected transfers to happen.

const stxPostCondition: StxPostCondition = {
  type: 'stx-postcondition',
  address: 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM',
  condition: 'eq',
  amount: '10000000',
};

const response = await request("stx_callContract", {
  contract: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.post-conditions",
  functionName: "single-stx-transfer",
  functionArgs: [],
  postConditionMode: "deny",
  postConditions: [stxPostCondition],
  network: "devnet"
})

User Expectation: Allow only 10 STX to be transferred.

Result: 10 STX are transferred from the sender's wallet as the user expected. Transaction is confirmed.

Multiple STX transfers

When multiple transfer events happen for the same asset on the same address, your post-condition statement should aggregate the net total amount of that asset being transferred during the execution of the entire function.

The contract first transfers 20 STX then transfers another 10 STX from the sender.

(define-public (multiple-stx-transfers)
  (begin
    (try! (stx-transfer? u20000000 tx-sender (as-contract tx-sender)))
    (unwrap! (get-burn-block-info? header-hash burn-block-height) (err u1001))
    (stx-transfer? u10000000 tx-sender (as-contract tx-sender))
  )
)

As the dev, you should notice that a total of 30 STX will be transferred from the user to the contract. This total amount should be accounted for as a single StxPostCondition since it's on the same asset and same principal. The postConditionMode is set to deny.

const stxPostCondition: StxPostCondition = {
  type: 'stx-postcondition',
  address: 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM',
  condition: 'lte',
  amount: '30000000',
};

const response = await request("stx_callContract", {
  contract: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.post-conditions",
  functionName: "multiple-stx-transfers",
  functionArgs: [],
  postConditionMode: "deny",
  postConditions: [stxPostCondition],
  network: "devnet"
})

User Expectation: Allow less than 30 STX to be transferred.

Result: 30 STX was transferred out of the sender's wallet as expected. Transaction is confirmed.

Mint and Burn Events

A post-condition statement is needed for burn events, but not needed for mint events.

(define-public (mint-and-burn-events)
  (begin
    (try! (stx-burn? u10000000 tx-sender))
    (contract-call? .good-token mint u5000000)
  )
)

A post-condition for the burn event will only be needed. Mint events are not considered a transfer and are treated differently.

const stxPostCondition: StxPostCondition = {
  type: "stx-postcondition",
  address: userStxAddress.value,
  condition: "eq",
  amount: "10000000"
}

const response = await request("stx_callContract", {
  contract: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.post-conditions",
  functionName: "mint-and-burn-events",
  functionArgs: [],
  postConditionMode: "deny",
  postConditions: [stxPostCondition],
  network: "devnet"
})

User Expectation: Allow exactly 10 STX to be transferred for burning.

Result: 10 STX transferred out of the sender's wallet to be burned. Some good-token were minted to the user. No other asset transfers happened. Transaction is confirmed.

Uncertain asset transfer amount

The function below demonstrates a scenario where the amount of STX to send is dynamic and uncertain. Having two post-condition statements that capture a range would be appropriate.

(define-public (uncertain-asset-amount)
  (let ((amount-to-send (mod (unwrap-panic (get-stacks-block-info? time (- stacks-block-height u1)))
      u21
    )))
    (try! (stx-transfer? amount-to-send tx-sender (as-contract tx-sender)))
    (ok (print amount-to-send))
  )
)

We're able to setup an amount range using post-conditions. We'll have one post-condition specifying that the user will transfer greater than or equal 0 STX, and another specifying that the user will transfer less than or equal to 1 STX.

const stxPostCondition: StxPostCondition = {
  type: "stx-postcondition",
  address: userStxAddress.value,
  condition: "gte",
  amount: "0"
}

const stxPostCondition1: StxPostCondition = {
  type: "stx-postcondition",
  address: userStxAddress.value,
  condition: "lte",
  amount: "1000000"
}

const response = await request("stx_callContract", {
  contract: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.post-conditions",
  functionName: "uncertain-asset-amount",
  functionArgs: [],
  postConditionMode: "deny",
  postConditions: [stxPostCondition, stxPostCondition1],
  network: "devnet"
})

User Expectation: Allow between 0 STX and 1 STX to be transferred from the user.

Result: If the actual amount of STX is within the specified expectated range, the transaction will confirm. If not, the transaction will abort and fail.

Hidden asset transfers

The function below contains a bunch of asset transfer events that are obfiscated in a way where it may not be noticeable at first glance. It's setup for the tx-sender to pay for a cool-nft for 2 STX, but unbeknownst to the user, the function will attempt to transfer out a few of the user's good tokens AND send the users some evil tokens.

(define-data-var nft-ids-sent uint u0)

(define-public (hidden-asset-transfers)
  (let ((nft-id (- (unwrap-panic (contract-call? .cool-nft get-last-token-id))
      (var-get nft-ids-sent)
    )))
    (try! (stx-transfer? u2000000 tx-sender (as-contract tx-sender)))
    (try! (drain-attempt))
    (try! (contract-call? .cool-nft transfer nft-id (as-contract tx-sender) tx-sender))
    (ok (var-set nft-ids-sent (+ u1 (var-get nft-ids-sent))))
  )
)

(define-private (drain-attempt)
  (let ((amount-to-drain (unwrap-panic (contract-call? .good-token get-balance tx-sender))))
    (try! (contract-call? .good-token transfer
      (- amount-to-drain (- amount-to-drain u10)) tx-sender
      (as-contract tx-sender) none
    ))
    (contract-call? .evil-token transfer u100000000 (as-contract tx-sender)
      tx-sender none
    )
  )
)

In this scenario, we'll simulate a failed transaction as a way to demonstrate where the dev and the user are both unaware of a few underlying transfers happening. Currently, the user assumes they will transfer 2 STX to receive a cool-nft asset.

We'll specify those 2 corresponding post-conditions with the post-condition mode set to deny. But when the transaction is executed and evaluated, it will fail because other previously unknown transfer events tried to execute saving our user from malicious activity.

const stxPostCondition: StxPostCondition = {
  type: "stx-postcondition",
  address: userStxAddress.value,
  condition: "lte",
  amount: "2000000"
}

const nftPostCondition1: NonFungiblePostCondition = {
  address: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.nft-contract",
  asset: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.cool-nft::cool-nft",
  assetId: Cl.uint(nftIdNonce.value),
  condition: "sent",
  type: "nft-postcondition"
}

const response = await request("stx_callContract", {
  contract: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.nft-contract",
  functionName: "hidden-asset-transfers",
  functionArgs: [],
  postConditionMode: "deny",
  postConditions: [stxPostCondition, nftPostCondition1],
  network: "devnet"
})

User Expectation: Allow the transfer of 2 STX for a cool-nft asset.

Result: The contract attempted to perform other asset transfers that were not covered by the declared post-conditions. Transaction will abort and fail.

PreviousImplementation NextsBTC

Last updated 20 hours ago

Was this helpful?

Good night

hashtagNo transfers

hashtagSingle STX transfer

hashtagMultiple STX transfers

hashtagMint and Burn Events

hashtagUncertain asset transfer amount