@eliseev_s/tolk-tlb-transpiler/README.md

Transpile Tolk structs to TLB definitions and generate TypeScript wrappers for TON blockchain smart contracts

# Tolk-TLB Transpiler

A powerful tool for transpiling Tolk structs to TLB (Type Language Binary) definitions and generating TypeScript wrappers for TON blockchain smart contracts.

## Features

-   🔄 **TLB Transpilation**: Convert Tolk structs to TLB schema definitions
-   🎯 **TypeScript Wrapper Generation**: Generate complete smart contract wrappers
-   🛠️ **CLI & API**: Use via command line or programmatic API
-   📦 **Type Safety**: Full TypeScript support with type definitions

## Installation

```bash
npm install -g @eliseev_s/tolk-tlb-transpiler
```

Or use directly:

```bash
npx tolk-tlb-transpiler --help
```

## CLI Usage

### Basic TLB Transpilation

```bash
# Transpile Tolk structs to TLB definitions
tolk-tlb transpile input.tolk

# Custom output directory
tolk-tlb transpile input.tolk -o ./output

# Skip TypeScript generation
tolk-tlb transpile input.tolk --no-ts

# Verbose output
tolk-tlb transpile input.tolk -v
```

### Smart Contract Wrapper Generation

```bash
# Generate TypeScript wrapper for smart contract
tolk-tlb wrapper structures.tolk get-methods.tolk MyContract

# Custom output directory
tolk-tlb wrapper structures.tolk get-methods.tolk MyContract -o ./output

# Custom file name
tolk-tlb wrapper structures.tolk get-methods.tolk MyContract -n contract-wrapper

# Verbose output
tolk-tlb wrapper structures.tolk get-methods.tolk MyContract -v
```

## Programmatic API

### Basic Transpilation

```typescript
import { transpileTolkToTlb, transpileTolkToTlbDefinitions } from 'tolk-tlb-transpiler';

const tolkCode = `
struct User {
    id: uint64;
    name: bytes;
    active: bool;
}
`;

// Get formatted TLB string
const tlbString = await transpileTolkToTlb(tolkCode);

// Get TLB definitions array
const tlbDefinitions = await transpileTolkToTlbDefinitions(tolkCode);
```

### Smart Contract Wrapper Generation

```typescript
import { generateContractWrapper } from 'tolk-tlb-transpiler';

const structuresCode = `
struct MinterStorage {
    counter: uint64;
    owner: address;
}

struct IncrementMessage {
    amount: uint32;
}

type MinterInternalMessage = IncrementMessage;
`;

const getMethodsCode = `
get counter(): uint64;
get owner(): address;
`;

const result = await generateContractWrapper(structuresCode, getMethodsCode, 'Minter');

// Access generated code
console.log(result.tlbString); // TLB definitions
console.log(result.typescriptCode); // TypeScript types
console.log(result.wrapperCode); // Contract wrapper class
console.log(result.fullCode); // Complete combined code
```

## Input/Output Examples

### TLB Transpilation

**Input (`user.tolk`):**

```tolk
struct User {
    id: uint64;
    data: cell;
    active: bool;
}
```

**Output (`user.tlb`):**

```tlb
// User
user#_ id:uint64 data:^Cell name:bytes active:bool = User;
```

### Wrapper Generation

**Input Files:**

`structures.tolk`:

```tolk
struct CounterStorage {
    counter: uint64;
    owner: address;
}

struct IncrementMessage {
    amount: uint32;
}

type CounterInternalMessage = IncrementMessage;
```

`get-methods.tolk`:

```tolk
get counter(): uint64;
get owner(): address;
```

**Generated Wrapper:**

```typescript
export class Counter implements Contract {
    constructor(readonly address: Address, readonly init?: { code: Cell; data: Cell }) {}

    static createFromAddress(address: Address) {
        return new Counter(address);
    }

    static createFromConfig(storage: CounterStorage, code: Cell, workchain = 0) {
        const data = beginCell().store(storeCounterStorage(storage)).endCell();
        const init = { code, data };
        return new Counter(contractAddress(workchain, init), init);
    }

    async sendIncrement(
        provider: ContractProvider,
        via: Sender,
        value: bigint,
        params: OmitKind<IncrementMessage>
    ) {
        await provider.internal(via, {
            value,
            sendMode: SendMode.PAY_GAS_SEPARATELY,
            body: beginCell()
                .store(storeIncrementMessage({ ...params, kind: 'IncrementMessage' }))
                .endCell(),
        });
    }

    async getCounter(provider: ContractProvider): Promise<bigint> {
        const { stack } = await provider.get('counter', []);
        return stack.readBigNumber();
    }

    async getOwner(provider: ContractProvider): Promise<Address> {
        const { stack } = await provider.get('owner', []);
        return stack.readAddress();
    }
}
```

## Command Reference

```bash
# Show help
tolk-tlb --help

# Show version
tolk-tlb --version

# Transpile command help
tolk-tlb transpile --help

# Wrapper command help
tolk-tlb wrapper --help
```

## Requirements

-   Node.js 16+
-   TypeScript 5.0+ (for development)

## Changelog

### v0.0.6

-   ✨ **New Feature**: Smart contract wrapper generation
-   🔧 **Enhancement**: Refactored `WrapperGenerator` to instance-based architecture
-   📝 **CLI**: Added `wrapper` command for generating TypeScript wrappers
-   🎯 **API**: Added `generateContractWrapper` function for programmatic usage
-   🛠️ **Architecture**: Improved code organization with factory pattern

### v0.0.5 and earlier

-   🔄 Basic TLB transpilation from Tolk structs
-   🛠️ CLI support for transpilation
-   📦 TypeScript type generation
-   🎯 Programmatic API for transpilation

## License

MIT