feat(sdk-py): bridge withdrawal

bindings/bindings.go

@@ -2762,3 +2762,83 @@ func CreateValueEqualsMarket(
 
 	return CreateMarket(client, bridge, queryComponents, settleTime, maxSpread, minOrderSize)
 }
+
+// ═══════════════════════════════════════════════════════════════
+//           BRIDGE FUNCTIONS
+// ═══════════════════════════════════════════════════════════════
+
+// GetWalletBalance retrieves the wallet balance for a specific bridge instance
+func GetWalletBalance(client *tnclient.Client, bridgeIdentifier string, walletAddress string) (string, error) {
+	ctx := context.Background()
+	balance, err := client.GetWalletBalance(ctx, bridgeIdentifier, walletAddress)
+	if err != nil {
+		return "", errors.Wrap(err, "failed to get wallet balance")
+	}
+	return balance, nil
+}
+
+// Withdraw performs a withdrawal operation by bridging tokens from TN to a destination chain
+func Withdraw(client *tnclient.Client, bridgeIdentifier string, amount string, recipient string) (string, error) {
+	ctx := context.Background()
+	txHash, err := client.Withdraw(ctx, bridgeIdentifier, amount, recipient)
+	if err != nil {
+		return "", errors.Wrap(err, "failed to withdraw tokens")
+	}
+	return txHash, nil
+}
+
+// GetWithdrawalProof retrieves the proofs and signatures needed to claim a withdrawal on EVM.
+func GetWithdrawalProof(client *tnclient.Client, bridgeIdentifier string, wallet string) (string, error) {
+	ctx := context.Background()
+
+	input := types.GetWithdrawalProofInput{
+		BridgeIdentifier: bridgeIdentifier,
+		Wallet:           wallet,
+	}
+
+	actions, err := client.LoadActions()
+	if err != nil {
+		return "", errors.Wrap(err, "failed to load actions")
+	}
+
+	results, err := actions.GetWithdrawalProof(ctx, input)
+	if err != nil {
+		return "", errors.Wrap(err, "failed to get withdrawal proof")
+	}
+
+	jsonBytes, err := json.Marshal(results)
+	if err != nil {
+		return "", errors.Wrap(err, "failed to marshal withdrawal proofs")
+	}
+
+	return string(jsonBytes), nil
+}
+
+// GetHistory retrieves the transaction history for a wallet on a specific bridge
+func GetHistory(client *tnclient.Client, bridgeIdentifier string, wallet string, limit int, offset int) (string, error) {
+	ctx := context.Background()
+
+	input := types.GetHistoryInput{
+		BridgeIdentifier: bridgeIdentifier,
+		Wallet:           wallet,
+		Limit:            &limit,
+		Offset:           &offset,
+	}
+
+	actions, err := client.LoadActions()
+	if err != nil {
+		return "", errors.Wrap(err, "failed to load actions")
+	}
+
+	results, err := actions.GetHistory(ctx, input)
+	if err != nil {
+		return "", errors.Wrap(err, "failed to get bridge history")
+	}
+
+	jsonBytes, err := json.Marshal(results)
+	if err != nil {
+		return "", errors.Wrap(err, "failed to marshal bridge history")
+	}
+
+	return string(jsonBytes), nil
+}

docs/api-reference.md

@@ -1360,4 +1360,95 @@ A YES price of 60 cents implies:
 - Each share pair requires $1.00 collateral
 - Winners receive $1.00 per winning share
 - Collateral from losing positions funds winner payouts
-- Supported bridges: `hoodi_tt2` (testnet)
+- Supported bridges: `hoodi_tt2` (testnet)
+
+## Attestation Helpers
+
+### `TNClient.parse_attestation_payload(payload: bytes) -> Dict[str, Any]`
+
+Parses a canonical attestation payload (without signature) into structured data.
+
+**Parameters:**
+- `payload: bytes` - The canonical payload from `GetSignedAttestation` (excluding the last 65 bytes of signature).
+
+**Returns:**
+- `Dict[str, Any]` - Structured dictionary containing:
+  - `version: int`
+  - `algorithm: int`
+  - `block_height: int`
+  - `data_provider: str` (0x-prefixed address)
+  - `stream_id: str`
+  - `action_id: int`
+  - `arguments: List[Any]` (decoded arguments)
+  - `result: List[Dict[str, Any]]` (decoded result rows)
+
+## Bridge Actions
+
+The Bridge Actions interface enables programmatic interaction with the TRUF.NETWORK bridge system. It allows bots and applications to manage token balances, initiate withdrawals to external chains, and retrieve cryptographic proofs for claiming assets.
+
+### `client.get_wallet_balance(bridge_identifier: str, wallet_address: str) -> str`
+
+Retrieves the token balance for a wallet on a specific bridge instance.
+
+**Parameters:**
+- `bridge_identifier: str` - Unique identifier for the bridge (e.g., "hoodi_tt", "sepolia").
+- `wallet_address: str` - The wallet address to query (0x-prefixed).
+
+**Returns:**
+- `str` - The balance in wei (as a string to preserve precision).
+
+**Example:**
+```python
+balance = client.get_wallet_balance("hoodi_tt", "0x123...")
+print(f"Balance: {int(balance) / 1e18} TT")
+```
+
+### `client.withdraw(bridge_identifier: str, amount: str, recipient: str) -> str`
+
+Initiates a withdrawal by burning tokens on the TRUF.NETWORK. This is the first step in bridging assets back to an external chain.
+
+**Parameters:**
+- `bridge_identifier: str` - Unique identifier for the bridge (e.g., "hoodi_tt").
+- `amount: str` - The amount to withdraw in wei. Must be a valid numeric string.
+- `recipient: str` - The EVM address that will receive the funds on the destination chain.
+
+**Returns:**
+- `str` - The transaction hash of the burn operation on Kwil.
+
+**Example:**
+```python
+# Withdraw 1 token (18 decimals)
+tx_hash = client.withdraw(
+    bridge_identifier="hoodi_tt", 
+    amount="1000000000000000000", 
+    recipient="0xRecipient..."
+)
+print(f"Burn TX Hash: {tx_hash}")
+```
+
+### `client.get_withdrawal_proof(bridge_identifier: str, wallet: str) -> List[Dict]`
+
+Retrieves the cryptographic proofs required to claim a withdrawal on the destination chain.
+
+**Parameters:**
+- `bridge_identifier: str` - The bridge ID (e.g., "hoodi_tt").
+- `wallet: str` - The wallet address that initiated the withdrawal.
+
+**Returns:**
+- `List[Dict]` - A list of proof objects, each containing:
+  - `block_height: int`
+  - `block_hash: str` (Base64)
+  - `root: str` (Base64)
+  - `signatures: List[str]` (Base64)
+  - `amount: str`
+  - `recipient: str`
+
+**Example:**
+```python
+proofs = client.get_withdrawal_proof("hoodi_tt", "0xSender...")
+
+if proofs:
+    proof = proofs[0]
+    print(f"Ready to claim {proof['amount']} tokens")
+    # Use proof data to submit claim transaction on Ethereum
+```