Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs libraries migration #52

Merged
merged 1 commit into from
Nov 2, 2023
Merged

docs libraries migration #52

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion 01-wallet/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,7 @@ npm install ts-node
---
library:npmton
---
Next, we're going to install a JavaScript package named [ton](https://www.npmjs.com/package/ton) that will allow us to make TON API calls and manipulate TON objects. Install the package by opening terminal in the project directory and running:
Next, we're going to install a JavaScript package named [@ton/ton](https://www.npmjs.com/package/@ton/ton) that will allow us to make TON API calls and manipulate TON objects. Install the package by opening terminal in the project directory and running:

```console
npm install @ton/ton @ton/crypto @ton/core
Expand Down
36 changes: 18 additions & 18 deletions 02-contract/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ Let's start with the first section, *storage*, and implement two utility functio
}

() save_data(int counter) impure inline { ;; write function declaration - takes an int as arg
set_data(begin_cell() ;; store the storage cell and create it with a builder
set_data(begin_cell() ;; store the storage cell and create it with a builder
.store_uint(counter, 64) ;; write a 64 bit unsigned int to the builder
.end_cell()); ;; convert the builder to a cell
}
Expand Down Expand Up @@ -130,14 +130,14 @@ That's it. We completed our 3 sections and the first version of our contract is

## Step 6: Build the counter contract

Right now, the contract is just FunC source code. To get it to run on-chain, we need to convert it to TVM [bytecode](https://ton.org/docs/learn/tvm-instructions/instructions).
Right now, the contract is just FunC source code. To get it to run on-chain, we need to convert it to TVM [bytecode](https://ton.org/docs/learn/tvm-instructions/instructions).

In TON, we don't compile FunC directly to bytecode, but instead go through another programming language called [Fift](https://ton-blockchain.github.io/docs/fiftbase.pdf). Just like FunC, Fift is another language that was designed specifically for TON Blockchain. It's a low level language that is very close to TVM opcodes. For us regular mortals, Fift is not very useful, so unless you're planning on some extra advanced things, I believe you can safely ignore it for now.

Since we're using func-js for building, it would be a good idea to create a directory where we can store the build result. To do this, open the terminal and run the following command:

```console
mkdir build
mkdir build
```

The func-js package contains everything we need to compile our contract to bytecode. To use it, open terminal in the project directory and run the following:
Expand Down Expand Up @@ -166,7 +166,7 @@ The recommended way to interact with contracts is to create a small TypeScript c
Use the following code in `wrappers/Counter.ts` to create the initial data cell for deployment:

```ts
import { Contract, ContractProvider, Sender, Address, Cell, contractAddress, beginCell } from "ton-core";
import { Contract, ContractProvider, Sender, Address, Cell, contractAddress, beginCell } from "@ton/core";

export default class Counter implements Contract {

Expand All @@ -178,12 +178,12 @@ export default class Counter implements Contract {
const address = contractAddress(workchain, { code, data });
return new Counter(address, { code, data });
}

constructor(readonly address: Address, readonly init?: { code: Cell, data: Cell }) {}
}
```

Notice a few interesting things about this TypeScript code. First, it depends on the package [ton-core](https://www.npmjs.com/package/ton-core) instead of [ton](https://www.npmjs.com/package/ton), which contains a small subset of base types and is therefore slower to change - an important feature when building a stable interface for our contract. Second, the code that creates the data cell mimics the FunC API and is almost identical to our `save_data()` FunC function. Third, we can see the derivation of the contract address from the code cell and data cell using the function `contractAddress`.
Notice a few interesting things about this TypeScript code. First, it depends on the package [@ton/core](https://www.npmjs.com/package/@ton/core) instead of [@ton/ton](https://www.npmjs.com/package/@ton/ton), which contains a small subset of base types and is therefore slower to change - an important feature when building a stable interface for our contract. Second, the code that creates the data cell mimics the FunC API and is almost identical to our `save_data()` FunC function. Third, we can see the derivation of the contract address from the code cell and data cell using the function `contractAddress`.

The actual deployment involves sending the first message that will cause our contract to be deployed. We can piggyback any message that is directed towards our contract. This can even be the increment message with op #1, but we will do something simpler. We will just send some TON coins to our contract (an empty message) and piggyback that. Let's make this part of our interface. Add the function `sendDeploy()` to `wrappers/Counter.ts` - this function will send the deployment message:

Expand Down Expand Up @@ -227,7 +227,7 @@ network:testnet
import * as fs from "fs";
import { getHttpEndpoint } from "@orbs-network/ton-access";
import { mnemonicToWalletKey } from "ton-crypto";
import { TonClient, Cell, WalletContractV4 } from "ton";
import { TonClient, Cell, WalletContractV4 } from "@ton/ton";
import Counter from "../wrappers/Counter"; // this is the interface class from step 7

export async function run() {
Expand All @@ -239,7 +239,7 @@ export async function run() {
const counterCode = Cell.fromBoc(fs.readFileSync("build/counter.cell"))[0]; // compilation output from step 6
const initialCounterValue = Date.now(); // to avoid collisions use current number of milliseconds since epoch as initial value
const counter = Counter.createForDeploy(counterCode, initialCounterValue);

// exit if contract is already deployed
console.log("contract address:", counter.address.toString());
if (await client.isContractDeployed(counter.address)) {
Expand All @@ -258,7 +258,7 @@ export async function run() {
const walletContract = client.open(wallet);
const walletSender = walletContract.sender(key.secretKey);
const seqno = await walletContract.getSeqno();

// send the deploy transaction
const counterContract = client.open(counter);
await counterContract.sendDeploy(walletSender);
Expand Down Expand Up @@ -287,7 +287,7 @@ network:mainnet
import * as fs from "fs";
import { getHttpEndpoint } from "@orbs-network/ton-access";
import { mnemonicToWalletKey } from "ton-crypto";
import { TonClient, Cell, WalletContractV4 } from "ton";
import { TonClient, Cell, WalletContractV4 } from "@ton/ton";
import Counter from "../wrappers/Counter"; // this is the interface class from step 7

export async function run() {
Expand All @@ -299,7 +299,7 @@ export async function run() {
const counterCode = Cell.fromBoc(fs.readFileSync("build/counter.cell"))[0]; // compilation output from step 6
const initialCounterValue = Date.now(); // to avoid collisions use current number of milliseconds since epoch as initial value
const counter = Counter.createForDeploy(counterCode, initialCounterValue);

// exit if contract is already deployed
console.log("contract address:", counter.address.toString());
if (await client.isContractDeployed(counter.address)) {
Expand All @@ -318,7 +318,7 @@ export async function run() {
const walletContract = client.open(wallet);
const walletSender = walletContract.sender(key.secretKey);
const seqno = await walletContract.getSeqno();

// send the deploy transaction
const counterContract = client.open(counter);
await counterContract.sendDeploy(walletSender);
Expand Down Expand Up @@ -393,7 +393,7 @@ Add the following to `wrappers/Counter.ts`:
// }
```

Notice that methods in the interface class that call getters must start with the word `get`. This prefix is a requirement of the [ton](https://www.npmjs.com/package/ton) TypeScript library. The resulting source file should look like [this](https://github.com/ton-community/tutorials/blob/main/02-contract/test/counter.step9.ts).
Notice that methods in the interface class that call getters must start with the word `get`. This prefix is a requirement of the [@ton/ton](https://www.npmjs.com/package/@ton/ton) TypeScript library. The resulting source file should look like [this](https://github.com/ton-community/tutorials/blob/main/02-contract/test/counter.step9.ts).

### Executing the call

Expand All @@ -406,7 +406,7 @@ network:testnet
---
```ts
import { getHttpEndpoint } from "@orbs-network/ton-access";
import { TonClient, Address } from "ton";
import { TonClient, Address } from "@ton/ton";
import Counter from "../wrappers/Counter"; // this is the interface class we just implemented

export async function run() {
Expand All @@ -432,7 +432,7 @@ network:mainnet
---
```ts
import { getHttpEndpoint } from "@orbs-network/ton-access";
import { TonClient, Address } from "ton";
import { TonClient, Address } from "@ton/ton";
import Counter from "../wrappers/Counter"; // this is the interface class we just implemented

export async function run() {
Expand Down Expand Up @@ -490,7 +490,7 @@ Add the following to `wrappers/Counter.ts`:

As you recall, the increment message is an [internal message](https://ton.org/docs/develop/smart-contracts/guidelines/internal-messages) that is encoded by convention with a 32 bit unsigned int in the beginning to describe the op and a 64 bit unsigned int after to describe the query id. The query id is relevant for messages that expect a response message to be sent back (the request and the response share the same query id).

Notice that methods in the interface class that send messages must start with the word `send`, another prefix requirement of the [ton](https://www.npmjs.com/package/ton) library. The resulting source file should look like [this](https://github.com/ton-community/tutorials/blob/main/02-contract/test/counter.step10.ts).
Notice that methods in the interface class that send messages must start with the word `send`, another prefix requirement of the [@ton/ton](https://www.npmjs.com/package/@ton/ton) library. The resulting source file should look like [this](https://github.com/ton-community/tutorials/blob/main/02-contract/test/counter.step10.ts).

### Executing the send

Expand All @@ -502,7 +502,7 @@ network:testnet
```ts
import { getHttpEndpoint } from "@orbs-network/ton-access";
import { mnemonicToWalletKey } from "ton-crypto";
import { TonClient, WalletContractV4, Address } from "ton";
import { TonClient, WalletContractV4, Address } from "@ton/ton";
import Counter from "../wrappers/Counter"; // this is the interface class we just implemented

export async function run() {
Expand Down Expand Up @@ -554,7 +554,7 @@ network:mainnet
```ts
import { getHttpEndpoint } from "@orbs-network/ton-access";
import { mnemonicToWalletKey } from "ton-crypto";
import { TonClient, WalletContractV4, Address } from "ton";
import { TonClient, WalletContractV4, Address } from "@ton/ton";
import Counter from "../wrappers/Counter"; // this is the interface class we just implemented

export async function run() {
Expand Down
12 changes: 6 additions & 6 deletions 03-client/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ npm install @ton/ton @ton/core @ton/crypto
npm install @orbs-network/ton-access
```

Last but not least, we will need to overcome [ton](https://www.npmjs.com/package/ton) library's reliance on Nodejs `Buffer` that isn't available in the browser. We can do that by installing a polyfill. Run the following in terminal:
Last but not least, we will need to overcome [@ton/ton](https://www.npmjs.com/package/@ton/ton) library's reliance on Nodejs `Buffer` that isn't available in the browser. We can do that by installing a polyfill. Run the following in terminal:

```console
npm install vite-plugin-node-polyfills
Expand Down Expand Up @@ -165,7 +165,7 @@ network:testnet
---
```ts
import { getHttpEndpoint } from '@orbs-network/ton-access';
import { TonClient } from 'ton';
import { TonClient } from "@ton/ton";
import { useAsyncInitialize } from './useAsyncInitialize';

export function useTonClient() {
Expand All @@ -185,7 +185,7 @@ network:mainnet
---
```ts
import { getHttpEndpoint } from '@orbs-network/ton-access';
import { TonClient } from 'ton';
import { TonClient } from "@ton/ton";
import { useAsyncInitialize } from './useAsyncInitialize';

export function useTonClient() {
Expand Down Expand Up @@ -214,7 +214,7 @@ import { Address, OpenedContract } from '@ton/core';
export function useCounterContract() {
const client = useTonClient();
const [val, setVal] = useState<null | number>();

const counterContract = useAsyncInitialize(async () => {
if (!client) return;
const contract = new Counter(
Expand Down Expand Up @@ -335,7 +335,7 @@ export function useCounterContract() {
const { sender } = useTonConnect();

const sleep = (time: number) => new Promise((resolve) => setTimeout(resolve, time));

const counterContract = useAsyncInitialize(async () => {
if (!client) return;
const contract = new Counter(
Expand Down Expand Up @@ -415,7 +415,7 @@ Time to rebuild the web app, run in terminal:
npm run dev
```

Then refresh the web browser viewing the URL shown on-screen. You should see a new "Increment" link on the bottom of the screen. I'm assuming that you're still on desktop, make a note of the counter value and click the link.
Then refresh the web browser viewing the URL shown on-screen. You should see a new "Increment" link on the bottom of the screen. I'm assuming that you're still on desktop, make a note of the counter value and click the link.

Since your mobile Tonkeeper wallet is connected, this action should reach the Tonkeeper mobile app and cause it to display a confirmation dialog. Notice that this dialog shows the gas cost of the transaction. Approve the transaction on the mobile app. Since the app and wallet are connected, your approval should reach the app and cause it to display an indication that the transaction was sent. As you recall, new transactions must wait until they're included in a block, so this should take 5-10 seconds.

Expand Down
2 changes: 1 addition & 1 deletion HELP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ If something in the tutorial isn't working, these are the possible causes:

The bottom of every tutorial contains a link to the full code of all steps (in the *Conclusion* section). The code is written as an automated test that we run a few times a week. Compare your code to the test code and try to find where you did something different.

A common mistake is trying to send transactions from a wallet contract that isn't deployed or funded. This can happen if you're setting the wrong wallet version. As explained in the first tutorial, check your wallet address in an explorer and if your wallet has a different version from "wallet v4 r2" you will need to modify the example code. Let's say for example that your version is "wallet v3 r2" and you're using [ton](https://www.npmjs.com/package/ton) library, then replace `WalletContractV4` with `WalletContractV3R2`.
A common mistake is trying to send transactions from a wallet contract that isn't deployed or funded. This can happen if you're setting the wrong wallet version. As explained in the first tutorial, check your wallet address in an explorer and if your wallet has a different version from "wallet v4 r2" you will need to modify the example code. Let's say for example that your version is "wallet v3 r2" and you're using [@ton/ton](https://www.npmjs.com/package/@ton/ton) library, then replace `WalletContractV4` with `WalletContractV3R2`.

2. **One of the libraries we depend on had a breaking change and the tutorial is out of date.**

Expand Down
Loading
Loading