Stellar Smart Contract Development with JavaScript/TypeScript

This project enables you to develop Stellar (Soroban) smart contracts quickly and easily using JavaScript/TypeScript. Instead of writing Rust, you can create Soroban contracts using familiar JavaScript syntax and decorators.

Purpose

Traditional Soroban contract development requires Rust knowledge. This tool allows JavaScript/TypeScript developers to:

• Simplify storage operations with decorators
• Define type-safe structs
• Rapidly prototype contracts
• Write contracts with familiar syntax

Getting Started

# Install dependencies
npm install jstellar
npx stellar build --path {YOUR_PATH_YOU_CAN_FIND_EXAMPLES_IN_THE_GITHUB_REPOSITORY}

Features

• Storage Decorators: Easy storage management with @Storage, @GetString, @GetNumber
• Struct Support: Complex data structures with @Struct, @GetStruct, @Field
• Type Safety: Type safety with TypeScript support
• Automatic Rust Conversion: Your JavaScript code is automatically converted to Rust

Tsconfig Sample

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "ts-node": {
    "transpileOnly": true,
    "compilerOptions": {
      "module": "commonjs"
    }
  }
}

Examples

Example 1: Basic Storage Operations (examples/hello.contract.ts)

import { GetNumber, GetString, Storage } from "../lib/stellar-js-decorator"

class TestWord {
    MY_NUMBER = 17
    MY_NAME = 'john doe'

    // Simple functions
    hello_number(){
        return 17
    }

    get_number(num: number){
        return num
    }

    get_name(){
        return this.MY_NAME
    }

    // Write to storage
    @Storage('name', 'akif')
    set_name(){}

    @Storage('my_num', 17)
    set_num(){}

    // Read from storage
    @GetString('name')
    get_stor_name(){}

    @GetNumber('my_num')
    get_num_stor(){}
}

export default TestWord

Features:

• @Storage(key, value): Save value to contract storage
• @GetString(key): Read string from storage
• @GetNumber(key): Read number from storage
• Class variables and methods automatically convert to contract functions

Example 2: Struct Operations (examples/hello2.contract.ts)

import { Field, GetStruct, Struct } from "../lib/stellar-js-decorator"

class Hello2Con {
    USER = {
        name: '',
        lastname: '',
        city: ''
    }

    TEAM = {
        name: '',
        foundation: ''
    }

    // Save struct to storage
    @Struct('strucuser', {name: 'akifcan', lastname: 'kara', city: 'izmir'})
    @Field('USER')
    set_struct(){}

    // Read struct from storage
    @GetStruct('strucuser')
    @Field('USER')
    get_struct_by_name(){}
}

export default Hello2Con

Features:

• @Struct(key, value): Save complex objects to storage
• @GetStruct(key): Read struct from storage
• @Field(fieldName): Specify which class variable to use
• Nested objects automatically convert to Rust structs

How It Works

1. Write in JavaScript/TypeScript: Write your contract with familiar syntax
2. Mark with Decorators: Use decorators for storage and struct operations
3. Automatic Rust Conversion: Code is automatically converted to Soroban-compatible Rust
4. Deploy and Invoke: Deploy and invoke using standard Stellar CLI

JavaScript to Rust Compilation Example

Here's how the JavaScript code from Example 2 compiles to Rust:

JavaScript Input (examples/hello2.contract.ts):

import { Field, GetStruct, Struct } from "../lib/stellar-js-decorator"

class Hello2Con {
    USER = {
        name: '',
        lastname: '',
        city: ''
    }

    TEAM = {
        name: '',
        foundation: ''
    }

    @Struct('strucuser', {name: 'akifcan', lastname: 'kara', city: 'izmir'})
    @Field('USER')
    set_struct(){}

    @GetStruct('strucuser')
    @Field('USER')
    get_struct_by_name(){}
}

export default Hello2Con

Compiled Rust Output:

#![no_std]
use soroban_sdk::{contract, contractimpl, contracttype, symbol_short, vec, Env, String, Vec};

#[contract]
pub struct Hello2Con;

#[contracttype]
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct USER {
    pub name: String,
    pub lastname: String,
    pub city: String
}

#[contracttype]
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct TEAM {
    pub name: String,
    pub foundation: String
}

#[contractimpl]
impl Hello2Con {
    pub fn set_struct(env: Env) {
        let key = symbol_short!("strucuser");
        let ss = USER {
            name: String::from_str(&env, "akifcan"),
            lastname: String::from_str(&env, "kara"),
            city: String::from_str(&env, "izmir"),
        };
        env.storage().instance().set(&key, &ss);
    }

    pub fn get_struct_by_name(env: Env) -> USER {
        let key = symbol_short!("strucuser");
        env.storage().instance().get(&key).unwrap()
    }
}

What happens during compilation:

• JavaScript class → Rust #[contract] struct
• Object definitions → Rust #[contracttype] structs with proper derives
• @Struct decorator → Storage write operation with struct initialization
• @GetStruct decorator → Storage read operation with type-safe return
• @Field decorator → Maps to the corresponding Rust struct type
• All Soroban SDK imports and boilerplate are automatically generated

Deploying the Contract

stellar contract deploy \
  --wasm target/wasm32-unknown-unknown/release/hello.wasm \
  --source-account akif \
  --network testnet

Invoking the Contract

# Simple function call
stellar contract invoke \
  --id CONTRACT_ID \
  --source-account akif \
  --network testnet \
  -- \
  get_number \
  --num 42

# Write to storage (--send=yes required)
stellar contract invoke \
  --id CONTRACT_ID \
  --source-account akif \
  --network testnet \
  --send=yes \
  -- \
  set_name

# Read from storage
stellar contract invoke \
  --id CONTRACT_ID \
  --source-account akif \
  --network testnet \
  -- \
  get_stor_name

Advantages

• Rapid Development: Write contracts without learning Rust
• Less Code: Decorators reduce boilerplate code
• Type Safety: Catch errors with TypeScript
• Easy Debugging: Use JavaScript tooling and debugging
• Stellar/Soroban Compatible: Full Soroban features support

Requirements

• Node.js
• TypeScript
• Stellar CLI
• Rust and Soroban SDK (for building)

Note: This tool is designed to help JavaScript developers quickly start working in the Stellar ecosystem. Thorough testing is recommended before using in production.