Xian Smart Contracts Cursor Rules

1# Xian Smart Contract Development - Cursor Rules
2 
3XIAN is the currency of the Xian blockchain.
4Never mention TAU or Lamden.
5 
6## Contract Structure
7 
8### Basic Structure
9- Smart contracts are written in native Python without transpilation
10- Contract names must follow the pattern: `^con_[a-z][a-z0-9_]*$`
11- Contract names must start with 'con_' prefix (except system contracts like 'currency')
12- Contract names must be lowercase, only contain letters, numbers and underscores after prefix
13- Contract names must be max 64 characters
14 
15### Naming Conventions
16- You cannot use '_' as a prefix for variables or functions (e.g., `_private_var` is not allowed)
17- Follow standard Python naming conventions otherwise
18- Use descriptive names for clarity
19- A contract can not be deployed by another contract
20 
21### Function Types
22- `@export` decorator defines public functions callable by any user or contract
23- `@construct` decorator defines initialization function executed once at contract submission (optional)
24- Functions without decorators are private and can only be called by the contract itself
25- Functions with `@export` can call private functions internally
26 
27### Constructor Arguments
28- Optional arguments can be provided to the `@construct` function
29- Initial state can be setup using these arguments
30 
31## State Management
32 
33### Variable
34- `Variable` is a way to define a singular state variable in the contract
35- Use `variable.set(value)` to modify
36- Use `variable.get()` to retrieve
37 
38```python
39my_var = Variable()
40 
41@construct
42def seed():
43    my_var.set(0)  # Initialize variable
44 
45@export
46def increment():
47    my_var.set(my_var.get() + 1)
48```
49 
50### Hash
51- `Hash` is a key-value store for the contract
52- Default value can be specified with `Hash(default_value=0)`
53- Access through dictionary-like syntax: `hash[key] = value` and `hash[key]`
54- Supports nested keys with tuple: `hash[key1, key2] = value`
55 
56```python
57my_hash = Hash(default_value=0)
58 
59@export
60def set_value(key: str, value: int):
61    my_hash[key] = value
62 
63@export
64def get_value(key: str):
65    return my_hash[key]
66```
67 
68#### Illegal Delimiters 
69":" and "." cannot be used in Variable or Hash keys.
70 
71### Foreign State Access
72- `ForeignHash` provides read-only access to a Hash from another contract
73- `ForeignVariable` provides read-only access to a Variable from another contract
74 
75```python
76token_balances = ForeignHash(foreign_contract='con_my_token', foreign_name='balances')
77foundation_owner = ForeignVariable(foreign_contract='foundation', foreign_name='owner')
78```
79 
80## Context Variables
81 
82### ctx.caller
83- The identity of the person or contract calling the function
84- Changes when a contract calls another contract's function
85- Used for permission checks in token contracts
86 
87### ctx.signer
88- The top-level user who signed the transaction
89- Remains constant throughout transaction execution
90- Only used for security guards/blacklisting, not for account authorization
91 
92### ctx.this
93- The identity/name of the current contract
94- Never changes
95- Useful when the contract needs to refer to itself
96 
97### ctx.owner
98- Owner of the contract, optional field set at time of submission
99- Only the owner can call exported functions if set
100- Can be changed with `ctx.owner = new_owner`
101 
102### ctx.entry
103- Returns tuple of (contract_name, function_name) of the original entry point
104- Helps identify what contract and function initiated the call chain
105 
106## Built-in Variables
107 
108### Time and Blockchain Information
109- `now` - Returns the current datetime
110- `block_num` - Returns the current block number, useful for block-dependent logic
111- `block_hash` - Returns the current block hash, can be used as a source of randomness
112 
113Example usage:
114```python
115@construct
116def seed():
117    submission_time = Variable()
118    submission_block_num = Variable()
119    submission_block_hash = Variable()
120    
121    # Store blockchain state at contract creation
122    submission_time.set(now)
123    submission_block_num.set(block_num)
124    submission_block_hash.set(block_hash)
125```
126 
127## Imports and Contract Interaction
128 
129### Importing Contracts
130- Use `importlib.import_module(contract_name)` for dynamic contract imports
131- Static contract imports can be done with `import <contract_name>`
132- Only use 'import' syntax for contracts, not for libraries or Python modules
133- Trying to import standard libraries will not work within a contract (they're automatically available)
134- Dynamic imports are preferred when the contract name is determined at runtime
135- Can enforce interface with `importlib.enforce_interface()`
136- NEVER import anything other than a contract.
137- ALL contracting libraries are available globally
138- NEVER IMPORT importlib. It is already available globally.
139 
140```python
141@export
142def interact_with_token(token_contract: str, recipient: str, amount: float):
143    token = importlib.import_module(token_contract)
144    
145    # Define expected interface
146    interface = [
147        importlib.Func('transfer', args=('amount', 'to')),
148        importlib.Var('balances', Hash)
149    ]
150    
151    # Enforce interface
152    assert importlib.enforce_interface(token, interface)
153    
154    # Call function on other contract
155    token.transfer(amount=amount, to=recipient)
156```
157 
158## Error Handling
159 
160### Assertions
161- Use `assert` statements for validation and error checking
162- Include error messages: `assert condition, "Error message"`
163 
164### No Try/Except
165- Exception handling with try/except is not allowed
166- Use conditional logic with if/else statements instead
167 
168```python
169# DO NOT USE:
170try:
171    result = 100 / value
172except:
173    result = 0
174 
175# CORRECT APPROACH:
176assert value != 0, "Cannot divide by zero"
177result = 100 / value
178 
179# OR
180if value == 0:
181    result = 0
182else:
183    result = 100 / value
184```
185 
186### Prohibited Built-ins
187- `getattr` is an illegal built-in function and must not be used
188- Other Python built-ins may also be restricted for security reasons
189 
190## Modules
191 
192### Random
193- Seed RNG with `random.seed()`
194- Generate random integers with `random.randint(min, max)`
195 
196### Datetime
197- Available by default without importing
198- Compare timestamps with standard comparison operators
199- Use the built-in `now` variable for current time
200 
201### Crypto
202- Provides cryptographic functionality using the PyNaCl library under the hood
203- Employs the Ed25519 signature scheme for digital signatures
204- Main function is `verify` for signature validation
205 
206```python
207# Verify a signature
208is_valid = crypto.verify(vk, msg, signature)
209# Returns True if the signature is valid for the given message and verification key
210```
211 
212Example usage in a contract:
213```python
214@export
215def verify_signature(vk: str, msg: str, signature: str):
216    # Use the verify function to check if the signature is valid 
217    is_valid = crypto.verify(vk, msg, signature)
218    
219    # Return the result of the verification
220    return is_valid
221```
222 
223### Hashlib
224- Xian provides a simplified version of hashlib with a different API than Python's standard library
225- Does not require setting up an object and updating it with bytes
226- Functions directly accept and return hexadecimal strings
227 
228```python
229# Hash a hex string with SHA3 (256 bit)
230hash_result = hashlib.sha3("68656c6c6f20776f726c64")  # hex for "hello world"
231 
232# If not a valid hex string, it will encode the string to bytes first
233text_hash = hashlib.sha3("hello world")
234 
235# SHA256 works the same way (SHA2 256-bit, used in Bitcoin)
236sha256_result = hashlib.sha256("68656c6c6f20776f726c64")
237```
238 
239## Testing
240 
241### Setting Up Tests
242- Use Python's unittest framework
243- Client available via `from contracting.client import ContractingClient`
244- Flush client before and after each test
245 
246### Setting Test Environment
247- Pass environment variables like `now` (datetime) in a dictionary
248 
249```python
250from contracting.stdlib.bridge.time import Datetime
251 
252env = {"now": Datetime(year=2021, month=1, day=1, hour=0)}
253result = self.some_contract.some_fn(some_arg=some_value, environment=env)
254```
255 
256### Specifying Signer
257- Specify the signer when calling contract functions in tests
258 
259```python
260result = self.some_contract.some_fn(some_arg=some_value, signer="some_signer")
261```
262 
263## Events
264 
265### Defining Events
266- Use `LogEvent` to define events at the top level of a contract
267- Each event has a name and a schema of parameters with their types
268- Set `idx: True` for parameters that should be indexed for querying
269 
270```python
271TransferEvent = LogEvent(
272    event="Transfer",
273    params={
274        "from": {'type': str, 'idx': True},
275        "to": {'type': str, 'idx': True},
276        "amount": {'type': (int, float, decimal)}
277    }
278)
279 
280ApprovalEvent = LogEvent(
281    event="Approval",
282    params={
283        "owner": {'type': str, 'idx': True},
284        "spender": {'type': str, 'idx': True},
285        "amount": {'type': (int, float, decimal)}
286    }
287)
288```
289 
290### Emitting Events
291- Call the event variable as a function and pass a dictionary of parameter values
292- All parameters defined in the event schema must be provided
293- Event parameters must match the specified types
294 
295```python
296@export
297def transfer(amount: float, to: str):
298    sender = ctx.caller
299    
300    # ... perform transfer logic ...
301    
302    # Emit the transfer event
303    TransferEvent({
304        "from": sender,
305        "to": to,
306        "amount": amount
307    })
308```
309 
310### Testing Events
311- Use `return_full_output=True` when calling contract functions in tests to capture events
312- Access events in the result dictionary's 'events' key
313- Assert on event types and parameters in tests
314 
315```python
316# In your test function
317result = self.contract.transfer(
318    amount=100,
319    to="recipient",
320    signer="sender",
321    return_full_output=True
322)
323 
324# Verify events
325events = result['events']
326assert len(events) == 1
327assert events[0]['event'] == 'Transfer'
328assert events[0]['from'] == 'sender'
329assert events[0]['to'] == 'recipient'
330assert events[0]['amount'] == 100
331```
332 
333### Common Event Types
334- Transfer: When value moves between accounts
335- Approval: When spending permissions are granted
336- Mint/Burn: When tokens are created or destroyed
337- StateChange: When significant contract state changes
338- ActionPerformed: When important contract actions execute
339 
340## Smart Contract Testing Best Practices
341 
342### Test Structure
343- Use Python's unittest framework for structured testing
344- Create a proper test class that inherits from `unittest.TestCase`
345- Implement `setUp` and `tearDown` methods to isolate tests
346- Define the environment and chain ID in setUp for consistent testing
347 
348```python
349class TestMyContract(unittest.TestCase):
350    def setUp(self):
351        # Bootstrap the environment
352        self.chain_id = "test-chain"
353        self.environment = {"chain_id": self.chain_id}
354        self.deployer_vk = "test-deployer"
355        
356        # Initialize the client
357        self.client = ContractingClient(environment=self.environment)
358        self.client.flush()
359        
360        # Load and submit the contract
361        with open('path/to/my_contract.py') as f:
362            code = f.read()
363            self.client.submit(code, name="my_contract", constructor_args={"owner": self.deployer_vk})
364            
365        # Get contract instance
366        self.contract = self.client.get_contract("my_contract")
367        
368    def tearDown(self):
369        # Clean up after each test
370        self.client.flush()
371```
372 
373### Test Organization
374- Group tests by functionality using descriptive method names
375- Follow the Given-When-Then pattern for clear test cases
376- Test both positive paths and error cases
377- Define all variables within the test, not in setUp
378- Define all variables and parameters used by a test WITHIN THE TEST, not within setUp
379- This ensures test isolation and prevents unexpected side effects between tests
380 
381```python
382def test_transfer_success(self):
383    # GIVEN a sender with balance
384    sender = "alice"
385    self.contract.balances[sender] = 1000
386    
387    # WHEN a transfer is executed
388    result = self.contract.transfer(amount=100, to="bob", signer=sender)
389    
390    # THEN the balances should be updated correctly
391    self.assertEqual(self.contract.balances["bob"], 100)
392    self.assertEqual(self.contract.balances[sender], 900)
393```
394 
395### Testing for Security Vulnerabilities
396 
397#### 1. Authorization and Access Control
398- Test that only authorized users can perform restricted actions
399- Verify that contract functions check `ctx.caller` or `ctx.signer` appropriately
400 
401```python
402def test_change_metadata_unauthorized(self):
403    # GIVEN a non-operator trying to change metadata
404    with self.assertRaises(Exception):
405        self.contract.change_metadata(key="name", value="NEW", signer="attacker")
406```
407 
408#### 2. Replay Attack Protection
409- Test that transaction signatures cannot be reused
410- Verify nonce mechanisms or one-time-use permits
411 
412```python
413def test_permit_double_spending(self):
414    # GIVEN a permit already used once
415    self.contract.permit(owner="alice", spender="bob", value=100, deadline=deadline, 
416                        signature=signature)
417    
418    # WHEN the permit is used again
419    # THEN it should fail
420    with self.assertRaises(Exception):
421        self.contract.permit(owner="alice", spender="bob", value=100, 
422                            deadline=deadline, signature=signature)
423```
424 
425#### 3. Time-Based Vulnerabilities
426- Test behavior around time boundaries (begin/end dates)
427- Test with different timestamps using the environment parameter
428 
429```python
430def test_time_sensitive_function(self):
431    # Test with time before deadline
432    env = {"now": Datetime(year=2023, month=1, day=1)}
433    result = self.contract.some_function(signer="alice", environment=env)
434    self.assertTrue(result)
435    
436    # Test with time after deadline
437    env = {"now": Datetime(year=2024, month=1, day=1)}
438    with self.assertRaises(Exception):
439        self.contract.some_function(signer="alice", environment=env)
440```
441 
442#### 4. Balance and State Checks
443- Verify state changes after operations
444- Test for correct balance updates after transfers
445- Ensure state consistency through complex operations
446 
447```python
448def test_transfer_balances(self):
449    # Set initial balances
450    self.contract.balances["alice"] = 1000
451    self.contract.balances["bob"] = 500
452    
453    # Perform transfer
454    self.contract.transfer(amount=300, to="bob", signer="alice")
455    
456    # Verify final balances
457    self.assertEqual(self.contract.balances["alice"], 700)
458    self.assertEqual(self.contract.balances["bob"], 800)
459```
460 
461#### 5. Signature Validation
462- Test with valid and invalid signatures
463- Test with modified parameters to ensure signatures aren't transferable
464 
465```python
466def test_signature_validation(self):
467    # GIVEN a properly signed message
468    signature = wallet.sign_msg(msg)
469    
470    # WHEN using the correct parameters
471    result = self.contract.verify_signature(msg=msg, signature=signature, 
472                                          public_key=wallet.public_key)
473    
474    # THEN verification should succeed
475    self.assertTrue(result)
476    
477    # BUT when using modified parameters
478    with self.assertRaises(Exception):
479        self.contract.verify_signature(msg=msg+"tampered", signature=signature, 
480                                     public_key=wallet.public_key)
481```
482 
483#### 6. Edge Cases and Boundary Conditions
484- Test with zero values, max values, empty strings
485- Test operations at time boundaries (exactly at deadline)
486- Test with invalid inputs and malformed data
487 
488```python
489def test_edge_cases(self):
490    # Test with zero amount
491    with self.assertRaises(Exception):
492        self.contract.transfer(amount=0, to="receiver", signer="sender")
493    
494    # Test with negative amount
495    with self.assertRaises(Exception):
496        self.contract.transfer(amount=-100, to="receiver", signer="sender")
497```
498 
499#### 7. Capturing and Verifying Events
500- Use `return_full_output=True` to capture events
501- Verify event emissions and their parameters
502 
503```python
504def test_event_emission(self):
505    # GIVEN a setup for transfer
506    sender = "alice"
507    receiver = "bob"
508    amount = 100
509    self.contract.balances[sender] = amount
510    
511    # WHEN executing with return_full_output
512    result = self.contract.transfer(
513        amount=amount, 
514        to=receiver, 
515        signer=sender,
516        return_full_output=True
517    )
518    
519    # THEN verify the event was emitted with correct parameters
520    self.assertIn('events', result)
521    events = result['events']
522    self.assertEqual(len(events), 1)
523    event = events[0]
524    self.assertEqual(event['event'], 'Transfer')
525    self.assertEqual(event['data_indexed']['from'], sender)
526    self.assertEqual(event['data_indexed']['to'], receiver)
527    self.assertEqual(event['data']['amount'], amount)
528```
529 
530### Common Exploits to Test For
531 
532#### Reentrancy
533- Test that state is updated before external calls
534- Verify operations complete atomically
535 
536```python
537def test_no_reentrancy_vulnerability(self):
538    # Set up the attack scenario (if possible with Xian)
539    
540    # Verify state is properly updated before any external calls
541    # For example, check that balances are decreased before tokens are sent
542    
543    # Verify proper operation ordering in the contract
544```
545 
546#### Integer Overflow/Underflow
547- Test with extremely large numbers
548- Test arithmetic operations at boundaries
549 
550```python
551def test_integer_boundaries(self):
552    # Set a large balance
553    self.contract.balances["user"] = 10**20
554    
555    # Test with large transfers
556    result = self.contract.transfer(amount=10**19, to="receiver", signer="user")
557    
558    # Verify results are as expected
559    self.assertEqual(self.contract.balances["user"], 9*10**19)
560    self.assertEqual(self.contract.balances["receiver"], 10**19)
561```
562 
563#### Front-Running Protection
564- Test mechanisms that prevent frontrunning (e.g., commit-reveal)
565- Test deadline-based protections
566 
567```python
568def test_front_running_protection(self):
569    # Test with deadlines to ensure transactions expire
570    deadline = Datetime(year=2023, month=1, day=1)
571    current_time = Datetime(year=2023, month=1, day=2)  # After deadline
572    
573    with self.assertRaises(Exception):
574        self.contract.time_sensitive_operation(
575            param1="value",
576            deadline=str(deadline),
577            environment={"now": current_time}
578        )
579```
580 
581#### Authorization Bypass
582- Test authorization for all privileged operations
583- Try to access functions with different signers
584 
585```python
586def test_authorization_checks(self):
587    # Test admin functions with non-admin signers
588    with self.assertRaises(Exception):
589        self.contract.admin_function(param="value", signer="regular_user")
590    
591    # Test with proper authorization
592    result = self.contract.admin_function(param="value", signer="admin")
593    self.assertTrue(result)
594```
595 
596### Best Practices Summary
597- Test both positive and negative paths
598- Test permissions and authorization thoroughly
599- Use environment variables to test time-dependent behavior
600- Verify event emissions using `return_full_output=True`
601- Test against potential replay attacks and signature validation
602- Check edge cases and boundary conditions
603- Verify state consistency after operations
604- Test for common security vulnerabilities