Skip to content

Commit

Permalink
docs: update
Browse files Browse the repository at this point in the history
  • Loading branch information
thekiba committed Feb 11, 2024
1 parent 4eb9e63 commit c784072
Show file tree
Hide file tree
Showing 4 changed files with 16 additions and 14 deletions.
14 changes: 8 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ This package uses [TLB-Parser](https://github.com/ton-community/tlb-parser) to g
## Installation

```bash
npm install @polyprogrammist_test/tlbgen
npm install @ton-community/tlb-codegen
```

## Usage
Expand All @@ -22,7 +22,7 @@ t$_ x:# y:(uint 5) = A;

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

It will create a file called `example.tlb.ts` with the following code:
Expand Down Expand Up @@ -51,15 +51,15 @@ export function storeA(a: A): (builder: Builder) => void {
}
```

You also can set an output file with `-o` option: `npx tlbgen -o other_file.ts example.tlb`.
You also can set an output file with `-o` option: `npx tlb -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).
One of the examples where you can see various abilities of the tool is [block.tlb](https://github.com/ton-blockchain/ton/blob/master/crypto/block/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"
import { generateCode } from "@ton-community/tlb-codegen"
generateCode('example.tlb', 'example.tlb.ts', "typescript")
```

Expand All @@ -80,7 +80,9 @@ Built-in types supported are:
- `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.
> 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](https://github.com/ton-org/ton-core) doesn't store the intermediate nodes. That is why `HashmapAugE` can be correctly loaded by the generated code, but storing is incorrect.
> Please note that `BinTree` is not supported yet. In the future it will be supported as built-in type `BinTree` from [@ton/core](https://github.com/ton-org/ton-core).
## License

Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
"compile": "tsc"
},
"bin": {
"tlbgen": "build/main.js"
"tlb": "build/main.js"
},
"keywords": [],
"author": "",
Expand Down
8 changes: 4 additions & 4 deletions test/generated_files/generated_block.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1013,7 +1013,7 @@ export interface Transaction {
}

/*
merkle_update#02 {X:Type} old_hash:bits256 new_hash:bits256
!merkle_update#02 {X:Type} old_hash:bits256 new_hash:bits256
old:^X new:^X = MERKLE_UPDATE X;
*/

Expand All @@ -1036,7 +1036,7 @@ export interface HASH_UPDATE<X> {
readonly new_hash: BitString;
}

// merkle_proof#03 {X:Type} virtual_hash:bits256 depth:uint16 virtual_root:^X = MERKLE_PROOF X;
// !merkle_proof#03 {X:Type} virtual_hash:bits256 depth:uint16 virtual_root:^X = MERKLE_PROOF X;

export interface MERKLE_PROOF<X> {
readonly kind: 'MERKLE_PROOF';
Expand Down Expand Up @@ -6757,7 +6757,7 @@ export function storeTransaction(transaction: Transaction): (builder: Builder) =
}

/*
merkle_update#02 {X:Type} old_hash:bits256 new_hash:bits256
!merkle_update#02 {X:Type} old_hash:bits256 new_hash:bits256
old:^X new:^X = MERKLE_UPDATE X;
*/

Expand Down Expand Up @@ -6826,7 +6826,7 @@ export function storeHASH_UPDATE<X>(hASH_UPDATE: HASH_UPDATE<X>, storeX: (x: X)

}

// merkle_proof#03 {X:Type} virtual_hash:bits256 depth:uint16 virtual_root:^X = MERKLE_PROOF X;
// !merkle_proof#03 {X:Type} virtual_hash:bits256 depth:uint16 virtual_root:^X = MERKLE_PROOF X;

export function loadMERKLE_PROOF<X>(slice: Slice, loadX: (slice: Slice) => X): MERKLE_PROOF<X> {
if (((slice.remainingBits >= 8) && (slice.preloadUint(8) == 0x03))) {
Expand Down
6 changes: 3 additions & 3 deletions test/tlb/block.tlb
Original file line number Diff line number Diff line change
Expand Up @@ -276,11 +276,11 @@ transaction$0111 account_addr:bits256 lt:uint64
total_fees:CurrencyCollection state_update:^(HASH_UPDATE Account)
description:^TransactionDescr = Transaction;

merkle_update#02 {X:Type} old_hash:bits256 new_hash:bits256
!merkle_update#02 {X:Type} old_hash:bits256 new_hash:bits256
old:^X new:^X = MERKLE_UPDATE X;
update_hashes#72 {X:Type} old_hash:bits256 new_hash:bits256
= HASH_UPDATE X;
merkle_proof#03 {X:Type} virtual_hash:bits256 depth:uint16 virtual_root:^X = MERKLE_PROOF X;
!merkle_proof#03 {X:Type} virtual_hash:bits256 depth:uint16 virtual_root:^X = MERKLE_PROOF X;

acc_trans#5 account_addr:bits256
transactions:(HashmapAug 64 ^Transaction CurrencyCollection)
Expand Down Expand Up @@ -935,4 +935,4 @@ chan_signed_msg$_ sig_A:(Maybe ^bits512) sig_B:(Maybe ^bits512) msg:ChanMsg = Ch
chan_op_cmd#912838d1 msg:ChanSignedMsg = ChanOp;


chan_data$_ config:^ChanConfig state:^ChanState = ChanData;
chan_data$_ config:^ChanConfig state:^ChanState = ChanData;

0 comments on commit c784072

Please sign in to comment.