Skip to content
Thru Docs

Common Patterns

View as Markdown

Use this page when you want a small, copyable pattern rather than a full API tour.

Validate the instruction header first

Section titled “Validate the instruction header first”
if( instr_sz < sizeof( my_instr_hdr_t ) ) tsdk_revert( 0x1000UL );

Validate account indices before dereferencing

Section titled “Validate account indices before dereferencing”
if( !tsdk_is_account_idx_valid( account_idx ) ) {
  tsdk_revert( 0x1001UL );
}

Read transaction instruction data once

Section titled “Read transaction instruction data once”
tsdk_txn_t const * txn = tsdk_get_txn( );
uchar const * instr = tsdk_txn_get_instr_data( txn );
ulong instr_sz = tsdk_txn_get_instr_data_sz( txn );

Make account data writable before mutation

Section titled “Make account data writable before mutation”
if( tsys_set_account_data_writable( account_idx ) != TSDK_SUCCESS ) {
  tsdk_revert( 0x1002UL );
}

Resize before writing a larger account payload

Section titled “Resize before writing a larger account payload”
if( tsys_account_resize( account_idx, sizeof( my_account_t ) ) != TSDK_SUCCESS ) {
  tsdk_revert( 0x1003UL );
}

Read and write packed account data carefully

Section titled “Read and write packed account data carefully”
my_account_t * account = (my_account_t *)tsdk_get_account_data_ptr( account_idx );
account->counter++;

If alignment is uncertain because you are reading from instruction bytes rather than account storage, prefer TSDK_LOAD and TSDK_STORE.

Bubble up CPI failures explicitly

Section titled “Bubble up CPI failures explicitly”
ulong invoke_err = 0UL;
ulong invoke_result = tsys_invoke( payload, payload_sz, target_program_idx, NULL, &invoke_err );


if( invoke_result != TSDK_SUCCESS ) tsdk_revert( invoke_result );
if( invoke_err    != TSDK_SUCCESS ) tsdk_revert( invoke_err );

Emit human-readable logs

Section titled “Emit human-readable logs”
tsdk_printf( "counter=%lu", counter_value );

Emit raw event payloads

Section titled “Emit raw event payloads”
if( tsys_emit_event( event_bytes, event_sz ) != TSDK_SUCCESS ) {
  tsdk_revert( 0x1004UL );
}

Derive a program-defined address

Section titled “Derive a program-defined address”
tn_pubkey_t derived[1];
tsdk_create_program_defined_account_address( owner, 0U, seed, derived );

Parse proof tails safely

Section titled “Parse proof tails safely”
if( remaining_sz < sizeof( tsdk_state_proof_hdr_t ) ) tsdk_revert( 0x1005UL );


tsdk_state_proof_hdr_t const * hdr =
  (tsdk_state_proof_hdr_t const *)proof_ptr;


ulong proof_sz = tsdk_state_proof_footprint_from_header( hdr );
if( remaining_sz < proof_sz ) tsdk_revert( 0x1006UL );

Notes

Section titled “Notes”
  • The most reliable flow is: validate sizes, validate indices, validate ownership or auth, then mutate or invoke.
  • If a page elsewhere shows a bigger end-to-end example, use this page as the short-form reference while implementing.