Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/covenant-gov/pacto-app/llms.txt

Use this file to discover all available pages before exploring further.

On-chain transactions must never freeze navigation or block the UI. Signing and broadcast typically take a few seconds, but receipt confirmation can take minutes on a congested network. Pacto handles this by broadcasting the transaction, releasing the UI immediately, and then continuing receipt polling entirely in the background — surfacing results via toasts and in-place card updates when they arrive.

​
Core rules

Four rules govern every on-chain action in Pacto:
  1. Broadcast, then release the UI. Once the signed transaction is submitted to the mempool, close modals and re-enable panels so the user can keep working.
  2. Show honest pending state. Use toasts (“submitted — confirmation continues in the background”), pending badges on DM wallet cards, and dashboard placeholders. Never claim final success before a confirmed receipt.
  3. Poll receipts off the critical path. Use wallet_wait_for_transaction (or domain-specific finalize logic) from a background task. Receipt polling times out after 180 seconds (RECEIPT_WAIT_TIMEOUT in wallet_ops.rs). On timeout, return RECEIPT_TIMEOUT with the txHash when known.
  4. Permanent DM announcements follow the optimistic two-phase pattern: append a local pending card immediately after broadcast, then patch it to confirmed (or failed) once the receipt arrives.

​
Backend commands

CommandDefaultNotes
wallet_build_and_send_transactionwaitForConfirmation: falseReturns txHash after broadcast; optionally returns blockNumber when waitForConfirmation: true.
wallet_wait_for_transaction—Polls receipt. Returns the same result shape as a confirmed send.
evm_send_advanced_contract_callwaitForConfirmation: falseUsed by the Settings → Advanced panel.
evm_send_squad_allowlisted_contract_callwaitForConfirmation: falseDashboard allowlist sends via squad-purpose signer.
Deploy / governance commandsReceipt-wait internalUI closes immediately; the invoke runs in a background job via runOnChainInBackground.

​
Frontend helpers

src/lib/evm/on-chain-background.ts provides the shared primitives for non-blocking on-chain work:
  • runOnChainInBackground — queues long-running Tauri invokes such as deploy wizards and squad admin writes so they don’t block the UI thread.
  • waitForOnChainConfirmationInBackground — polls for a receipt after a broadcast-only send; drives the optimistic card lifecycle.
  • toastOnChainSubmitted — shows a “submitted” toast with an explorer link after broadcast.
  • toastOnChainConfirmed — shows a success toast once the receipt arrives.
  • toastOnChainFailed — shows a failure toast on revert or timeout.
DM wallet sends additionally use finalizeWalletDmTransferAfterBroadcast in src/lib/wallet/wallet-dm-transfer.ts to drive the optimistic card state machine.

​
DM wallet transfers — optimistic flow

Sending tokens from the WalletBar in a DM thread follows a seven-step optimistic lifecycle:
  1. Broadcast the transaction via wallet_build_and_send_transaction (waitForConfirmation: false).
  2. Immediately append a local outbound DM row with pending: true and a wallet_tx_announcement payload — the card shows a “Transfer pending” badge.
  3. Close the send modal; show a toast with the explorer link.
  4. Background: call wallet_wait_for_transaction to poll for the receipt.
  5. On success: patch the local row to its confirmed content; relay the same wallet_tx_announcement JSON to the peer via Nostr; refresh balances; show a confirmation toast.
  6. On revert: patch the local row to failed: true; show a failure toast.
  7. On timeout: leave the card pending; show a toast telling the user to check the explorer. Do not claim success.
Inbound announcements relayed from peers are post-receipt only — they are never upgraded from a pending state. The optimistic two-phase pattern applies only to locally-originated sends.

​
UX stage reference

StageUser sees
Confirm clickedBrief signing / submit state (typically a few seconds).
Tx broadcastModal closes (or panel unlocks); toast with hash and explorer link; DM card shows pending badge.
Receipt successToast confirmation; pending UI updates to confirmed; DM announcement relayed to peer.
Receipt failure (revert)Toast with failure message; DM card shows failed badge.
Timeout (180 s)Toast prompting user to check explorer; DM card remains in pending state.

Build docs developers (and LLMs) love

Get started for freeTalk to us