Surf
Type-Safe TypeScript Interfaces & React Hooks for Aptos.
## Features - **No code-generation**: Interact with smart contracts using fully typed APIs based on static type inference. Inspired by [Viem](https://viem.sh/). - **Get rid of encoding/decoding**: Surf takes care of the complexities within the APIs, so you don't have to. - **Linting and Auto-Completion**: Enjoy a better development experience with type safety. No more guesswork for input and output. - **Both TypeScript Interfaces & React Hooks**: Easy to use, whether working with wallets or private keys. - **Low runtime cost & small bundle size**: [minzipped size: < 2 kB](https://bundlephobia.com/package/@thalalabs/surf). ## Overview ```TypeScript const client = createSurfClient(new Aptos()); const result = await client.useABI(COIN_ABI).entry.transfer({ functionArguments: ['0x1', 1], typeArguments: ['0x1::aptos_coin::AptosCoin'], account: Account.fromPrivateKey(...), }); const [balance] = await client.useABI(COIN_ABI).view.balance({ functionArguments: ['0x1'], typeArguments: ['0x1::aptos_coin::AptosCoin'], }); ``` When you input `client.useABI(COIN_ABI).view.` into your IDE, the auto-completion show as below. You could also see the input and output types for the function, all of which are statically inferred from the ABI.  ## Quick Start ### Installation ```shell npm i @thalalabs/surf @aptos-labs/ts-sdk ``` If you want to use the React Hooks, install the `@aptos-labs/wallet-adapter-react` additionally. Those React Hooks will be moved to a separate package in near future. ### Start Create the client: ```TypeScript import { createSurfClient } from '@thalalabs/surf'; import { Aptos, Network, AptosConfig } from '@aptos-labs/ts-sdk'; const client = createSurfClient(new Aptos( new AptosConfig({ network: Network.TESTNET }) )); ``` Surf infers types from ABI to give you the end-to-end type-safety from your Move contract to your frontend. So firstly, you need to prepare the ABI json object of your contract in TypeScript (You can get ABI from Aptos Explorer, for example: [0x1::coin](https://explorer.aptoslabs.com/account/0x1/modules/code/coin?network=testnet)): ```TypeScript const abi = {…} as const; ``` If type inference isn't working, it's likely you forgot to add the const assertion for the object. And make sure that you set `strict` to `true` in your `tsconfig.json` compiler options. ### Call View functions There are two ways to call a view function with the client: ```typescript // Option 1. Use the `useABI` interface const [balance] = await client.useABI(COIN_ABI).view.balance({ functionArguments: ['0x1'], typeArguments: ['0x1::aptos_coin::AptosCoin'], ledgerVersion: '562606728', // ledger_version is optional }); // Option 2. Create payload and use the `view` interface import { createViewPayload } from '@thalalabs/surf'; const payload = createViewPayload(COIN_ABI, { function: 'balance', functionArguments: ['0x1'], typeArguments: ['0x1::aptos_coin::AptosCoin'], // (optional) you can also override the address in ABI // address: "0x123" }); const [balance] = await client.view({ payload, options: { ledgerVersion: '562606728' }, // ledger_version is optional }); ``` Both of the interfaces can provide type safety. Calling `useABI` returns an object without any ABI parsing, so that the runtime cost is low. ### Submit Transaction Similar to the `view` function, there are also two ways to submit transactions. ```typescript // prepare your AptosAccount const account = /* your AptosAccount */; // Option 1. Use the `useABI` interface const { hash } = await client.useABI(COIN_ABI).entry.transfer({ functionArguments: ['0x1', 1], typeArguments: ['0x1::aptos_coin::AptosCoin'], account, }); // Option 2. Create payload and use the `submitTransaction` interface import { createEntryPayload } from "@thalalabs/surf"; const payload = createEntryPayload(COIN_ABI, { function: 'transfer', functionArguments: ['0x1', 1], typeArguments: ['0x1::aptos_coin::AptosCoin'], // (optional) you can also override the address in ABI // address: "0x123" }); const result = await client.submitTransaction({ payload, signer: account, }); ``` You can also simulate a transaction: ```typescript // prepare your AptosAccount const account = /* your AptosAccount */; // Option 1. Use the `useABI` interface const { hash } = await client.useABI(COIN_ABI).entry.transfer({ arguments: ['0x1', 1], type_arguments: ['0x1::aptos_coin::AptosCoin'], account, isSimulation: true, }); // Option 2. Create payload and use the `simulateTransaction` interface import { createEntryPayload } from "@thalalabs/surf"; const entryPayload = createEntryPayload(COIN_ABI, { function: 'transfer', arguments: ['0x1', 1], type_arguments: ['0x1::aptos_coin::AptosCoin'], }); const { hash } = await client.simulateTransaction({ payload, sender: account.accountAddress, publicKey: account.publicKey, }); ``` ### Get account resource To get account resource with type safety: ```typescript const { data } = await client.useABI(COIN_ABI).resource.CoinStore({ typeArguments: ['0x1::aptos_coin::AptosCoin'], account: '0x1', }); // Get property in the struct with type safety console.log(data.frozen); // It also works for nested struct type. // The `coin` property's type is 0x1::coin::Coin