Xian SDK

Build applications on the Xian blockchain using the xian-py Python SDK. Use when developing apps that interact with Xian — wallets, transactions, smart contracts, state queries, token transfers. Covers sync and async patterns.

Security Scan

The skill is an instruction-only reference for the xian-py SDK and what it requests and instructs is consistent with that purpose — no unexpected credentials, installs, or persistent privileges are requested.

Purpose & Capability

Name/description match the content: SKILL.md documents how to use the xian-py Python SDK (wallets, queries, txs, contracts). There are no unrelated requirements (no cloud credentials, no unrelated binaries).

Instruction Scope

Instructions are focused on SDK usage and sample code. They show how to create wallets, sign, query state, simulate transactions and deploy contracts. Examples include entering private keys directly (not a scope violation, but a security practice note — they warn "Keep secret!"). The docs reference node endpoints (e.g., http://node:26657) which is expected for blockchain interaction; users should be aware that using remote nodes exposes transaction metadata to those nodes.

Install Mechanism

No install spec in the skill bundle itself. SKILL.md suggests installing xian-py via pip (a normal, proportional mechanism). Nothing is downloaded from untrusted URLs and the skill does not write code to disk by itself.

Credentials

The skill declares no required environment variables, secrets, or config paths. Sample code uses private keys/wallets but does not request platform credentials. This is proportionate to a developer reference for an SDK.

Persistence & Privilege

always is false and there is no install step that requests persistent presence or modifies other skills/system-wide settings. The skill being user-invocable and allowing model invocation is the platform default and appropriate here.

Assessment

This skill is a documentation/instruction pack for the xian-py SDK and appears internally consistent. Before installing or using it: 1) verify the upstream xian-py package/repository (pip package name and source) to avoid installing a malicious package with the same name; 2) never hard-code private keys into scripts — use secure key management or environment secrets and avoid sharing code containing keys; 3) be careful which node endpoints you point to (public/third-party nodes can see transaction metadata); 4) run pip installs in a controlled environment (virtualenv) and review the actual package files if you have security concerns; 5) because the skill is instruction-only, it won’t itself write files or fetch code, but following its instructions (pip install, running Python code) can execute arbitrary code, so audit the xian-py package and its dependencies if you plan to run on sensitive systems.

Xian SDK Skill

Build applications on Xian using the xian-py Python SDK.

Installation

pip install xian-py

# With Ethereum wallet support
pip install "xian-py[eth]"

Quick Reference

from xian_py import Xian, Wallet

wallet = Wallet()  # New wallet
xian = Xian('http://node:26657', wallet=wallet)

# Common operations
balance = xian.get_balance(wallet.public_key)
state = xian.get_state('contract', 'variable', 'key')
result = xian.send(amount=100, to_address='recipient')
result = xian.send_tx('contract', 'function', {'arg': 'value'})
result = xian.submit_contract('name', code)

Wallets

Basic Wallet

from xian_py import Wallet

# Create new wallet (random seed)
wallet = Wallet()

# From existing private key
wallet = Wallet('ed30796abc4ab47a97bfb37359f50a9c362c7b304a4b4ad1b3f5369ecb6f7fd8')

print(wallet.public_key)   # Address
print(wallet.private_key)  # Keep secret!

HD Wallet (BIP39/BIP32)

from xian_py.wallet import HDWallet

# Create with new 24-word mnemonic
hd = HDWallet()
print(hd.mnemonic_str)  # Save this!

# Restore from mnemonic
hd = HDWallet('word1 word2 word3 ... word24')

# Derive Xian wallet
path = [44, 0, 0, 0, 0]  # m/44'/0'/0'/0'/0'
wallet = hd.get_wallet(path)

# Derive Ethereum wallet (requires eth extras)
eth_wallet = hd.get_ethereum_wallet(0)  # First account
eth_wallet2 = hd.get_ethereum_wallet(1)  # Second account

Signing & Verification

wallet = Wallet()

# Sign message
signature = wallet.sign_msg("Hello Xian")

# Verify
is_valid = wallet.verify_msg("Hello Xian", signature)

# Validate key format
Wallet.is_valid_key(wallet.public_key)  # True

Blockchain Queries

from xian_py import Xian

xian = Xian('http://node:26657')

# Balance (default: currency contract)
balance = xian.get_balance('address')

# Custom token balance
balance = xian.get_balance('address', contract='token_contract')

# Contract state
state = xian.get_state('contract_name', 'variable', 'key')

# Get contract source
source = xian.get_contract('contract_name', clean=True)

Transactions

Simple Token Transfer

from xian_py import Xian, Wallet

wallet = Wallet('your_private_key')
xian = Xian('http://node:26657', wallet=wallet)

# Send tokens (auto stamp calculation)
result = xian.send(amount=100, to_address='recipient')

if result['success']:
    print(f"TX: {result['tx_hash']}")

Contract Interaction

# Call any contract function
result = xian.send_tx(
    contract='currency',
    function='transfer',
    kwargs={'to': 'recipient', 'amount': 1000}
)

# With custom token
result = xian.send_tx(
    contract='my_token',
    function='transfer',
    kwargs={'to': 'recipient', 'amount': 500}
)

Stamp Estimation

from xian_py.transaction import simulate_tx, get_nonce

# Simulate to get stamp cost
payload = {
    "contract": "currency",
    "function": "transfer",
    "kwargs": {"to": "recipient", "amount": 100},
    "sender": wallet.public_key,
}

result = simulate_tx('http://node:26657', payload)
print(f"Stamps needed: {result['stamps_used']}")

Smart Contracts

Deploy Contract

code = '''
balances = Hash(default_value=0)

@construct
def seed():
    balances[ctx.caller] = 1_000_000

@export
def transfer(to: str, amount: float):
    assert amount > 0, "Amount must be positive"
    assert balances[ctx.caller] >= amount, "Insufficient balance"
    
    balances[ctx.caller] -= amount
    balances[to] += amount

@export
def balance_of(address: str) -> float:
    return balances[address]
'''

result = xian.submit_contract('my_token', code)
print(f"Deployed: {result['success']}")

Contract Patterns

See references/contract-patterns.md for common patterns (tokens, access control, pausable, upgrades).

Contract Validation

Validate against Xian standards:

from xian_py.validator import validate_contract, XianStandard

is_valid, errors = validate_contract(code)  # XSC001 default

# Specific standard
is_valid, errors = validate_contract(code, standard=XianStandard.XSC001)

if not is_valid:
    print(errors)

Read-Only Execution

Query contract without spending stamps:

from xian_py.transaction import simulate_tx

payload = {
    "contract": "my_token",
    "function": "balance_of",
    "kwargs": {"address": "some_address"},
    "sender": wallet.public_key,
}

result = simulate_tx('http://node:26657', payload)
print(f"Balance: {result['result']}")

Async Operations

For high-performance applications:

import asyncio
from xian_py import XianAsync, Wallet

async def main():
    wallet = Wallet()
    
    async with XianAsync('http://node:26657', wallet=wallet) as xian:
        # Concurrent queries
        balance, state = await asyncio.gather(
            xian.get_balance(wallet.public_key),
            xian.get_state('currency', 'balances', 'address')
        )
        
        # Send transaction
        result = await xian.send(amount=100, to_address='recipient')

asyncio.run(main())

Batch Operations

async def check_balances(addresses: list[str]):
    async with XianAsync('http://node:26657') as xian:
        balances = await asyncio.gather(*[
            xian.get_balance(addr) for addr in addresses
        ])
        return dict(zip(addresses, balances))

Sync Wrapper

Call async from sync code:

from xian_py import XianAsync, run_sync

def get_balance_sync(address: str) -> float:
    async def _get():
        async with XianAsync('http://node:26657') as xian:
            return await xian.get_balance(address)
    return run_sync(_get())

balance = get_balance_sync('address')

Encryption

Two-way encrypted messaging:

from xian_py import Wallet
from xian_py.crypto import encrypt, decrypt_as_sender, decrypt_as_receiver

sender = Wallet()
receiver = Wallet()

# Encrypt
encrypted = encrypt(sender.private_key, receiver.public_key, "Secret message")

# Decrypt as sender
msg = decrypt_as_sender(sender.private_key, receiver.public_key, encrypted)

# Decrypt as receiver  
msg = decrypt_as_receiver(sender.public_key, receiver.private_key, encrypted)

Error Handling

from xian_py import Xian, XianException

try:
    result = xian.send_tx('contract', 'function', {})
except XianException as e:
    print(f"Blockchain error: {e}")

Common Patterns

Token Transfer Service

class TokenService:
    def __init__(self, node_url: str, private_key: str):
        self.wallet = Wallet(private_key)
        self.xian = Xian(node_url, wallet=self.wallet)
    
    def transfer(self, to: str, amount: float, token: str = 'currency'):
        balance = self.xian.get_balance(self.wallet.public_key, contract=token)
        if balance < amount:
            raise ValueError(f"Insufficient: {balance} < {amount}")
        
        return self.xian.send_tx(token, 'transfer', {'to': to, 'amount': amount})

DEX Swap

async def swap(xian, dex: str, token_in: str, token_out: str, 
               amount: float, min_out: float):
    # Approve DEX
    await xian.send_tx(token_in, 'approve', {'to': dex, 'amount': amount})
    
    # Execute swap
    return await xian.send_tx(dex, 'swap', {
        'token_in': token_in,
        'token_out': token_out,
        'amount_in': amount,
        'min_amount_out': min_out
    })

Resources

• xian-py GitHub — Full SDK docs
• Xian Standard Contracts — Token standards
• xian.org — Project site