Skip to content

Commit

Permalink
Create README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
PolyProgrammist authored Jan 16, 2024
1 parent aff9e4b commit 9e6eb1d
Showing 1 changed file with 87 additions and 0 deletions.
87 changes: 87 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
# TLB Generator
This package allows you to generate `Typescript` code for serializing and deserializing structures according to the `TLB` scheme provided.

[Here](https://docs.ton.org/develop/data-formats/tl-b-language) you can find documentation for creating TLB schemes, and more advanced article is [here](https://docs.ton.org/develop/data-formats/tl-b-types).

This package uses [TLB-Parser](https://github.com/ton-community/tlb-parser) to get AST of the scheme.

## Installation

```bash
npm install @polyprogrammist_test/tlbgen
```

## Usage

### CLI

Create a file with TLB scheme according to the [documentation](https://docs.ton.org/develop/data-formats/tl-b-language). This is an example of such a file (call it `example.tlb`):
```
t$_ x:# y:(uint 5) = A;
```

Then do:
```bash
npx tlbgen example.tlb
```

It will create a file called `example.tlb.ts` with the following code:
```typescript
export interface A {
readonly kind: 'A';
readonly x: number;
readonly y: number;
}
export function loadA(slice: Slice): A {
let x: number = slice.loadUint(32);
let y: number = slice.loadUint(5);
return {
kind: 'A',
x: x,
y: y,
}

}
export function storeA(a: A): (builder: Builder) => void {
return ((builder: Builder) => {
builder.storeUint(a.x, 32);
builder.storeUint(a.y, 5);
})

}
```

You also can set an output file with `-o` option: `npx tlbgen -o other_file.ts example.tlb`.

One of the examples where you can see various abilities of the tool is [block.tlb](https://github.com/PolyProgrammist/tlbgenerator/blob/master/test/tlb/block.tlb). The generation result for it is [here](https://github.com/PolyProgrammist/tlbgenerator/blob/master/test/generated_files/generated_block.ts).

### Node JS
Also you can use the tool from inside JS or TS code.

```typescript
import { generateCode } from "@polyprogrammist_test/tlbgen"
generateCode('example.tlb', 'example.tlb.ts', "typescript")
```


## Integration with ton-core

It is integrated with [ton-core](https://github.com/ton-org/ton-core/) in a way it uses several built-in types from there.

Built-in types supported are:
- `Bool` -> `boolean` (loaded with `loadBoolean`, stored with `storeBit`)
- `MsgAddressInt` -> `Address` (loaded with `loadAddress`, stored with `storeAddress`)
- `MsgAddressExt` -> `ExternalAddress | null` (loaded with `loadMaybeExternalAddress`, stored with `storeAddress`)
- `MsgAddress` -> `Address | ExternalAddress | null` (loaded with `loadAddressAny`, stored with `storeAddress`)
- `VarUInteger` -> `bigint` (loaded with `loadVarUintBig`, stored with `storeVarUint`)
- `VarInteger` -> `bigint` (loaded with `loadVarIntBig`, stored with `storeVarInt`)
- `Bit` -> `boolean` (loaded with `loadBit`, stored with `storeBit`)
- `Grams` -> `bigint` (loaded with `loadCoins`, stored with `storeCoins`)
- `HashmapE n Value` -> `Dictionary<bigint, Value>` (or `Dictionary<number, Value>` if n <= 64) (loaded with `Dictionary.load`, stored with `storeDict`)
- `HashmapAugE n Value Extra` -> `Dictionary<bigint, {value: Value, extra: Extra}>` (or `number` instead of `bigint` if `n <= 64`) (loaded with `Dictionary.load`, stored with `storeDict`)

Please note that the tricky thing here with `HashmapAugE` is that in `TLB` scheme extra is [stored](https://github.com/ton-blockchain/ton/blob/062b7b4a92dd67e32d963cf3f04b8bc97d8b7ed5/crypto/block/block.tlb#L49) not only with values, but in intermediate nodes as well. However `Dictionary` in ton-core doesn't store the intermediate nodes. That is why `HashmapAugE` can be correctly loaded by the generated code, but storing is incorrect.

## License

This package is released under the [MIT License](LICENSE).

0 comments on commit 9e6eb1d

Please sign in to comment.