diff --git a/.eslintrc.js b/.eslintrc.js index c7903c6684d7f..4be723fd08ea8 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -32,6 +32,8 @@ module.exports = { 'next-env.d.ts', 'doc/book', 'external-crates', + 'storybook-static', + '.next', ], rules: { 'no-case-declarations': 'off', diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 8d723b77c2ec4..96c6d4cc1f58d 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1100,6 +1100,27 @@ importers: specifier: ^5.1.6 version: 5.1.6 + sdk/docs: + dependencies: + '@types/node': + specifier: ^20.4.2 + version: 20.4.2 + next: + specifier: ^13.4.10 + version: 13.4.10(react-dom@18.2.0)(react@18.2.0) + nextra: + specifier: ^2.10.0 + version: 2.10.0(next@13.4.10)(react-dom@18.2.0)(react@18.2.0) + nextra-theme-docs: + specifier: ^2.10.0 + version: 2.10.0(next@13.4.10)(nextra@2.10.0)(react-dom@18.2.0)(react@18.2.0) + react: + specifier: ^18.2.0 + version: 18.2.0 + react-dom: + specifier: ^18.2.0 + version: 18.2.0(react@18.2.0) + sdk/kiosk: dependencies: '@mysten/sui.js': @@ -10649,7 +10670,7 @@ packages: engines: {node: ^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7} hasBin: true dependencies: - caniuse-lite: 1.0.30001478 + caniuse-lite: 1.0.30001516 electron-to-chromium: 1.4.332 node-releases: 2.0.10 update-browserslist-db: 1.0.10(browserslist@4.21.5) diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index a6ce9bea04f97..5e6d3d67f6379 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -1,14 +1,15 @@ packages: - - 'sdk/**' - - 'apps/**' - - 'dapps/**' - - '!**/dist/**' - - '!sdk/typescript/*/**' - - '!sdk/typescript/builder' - - '!sdk/typescript/cryptography' - - '!sdk/typescript/faucet' - - '!sdk/typescript/transactions' - - '!sdk/typescript/client' - - '!sdk/typescript/verify' - - '!sdk/typescript/multisig' - - '!sdk/typescript/utils' + - 'sdk/**' + - 'apps/**' + - 'dapps/**' + - '!**/dist/**' + - '!**/.next/**' + - '!sdk/typescript/*/**' + - '!sdk/typescript/builder' + - '!sdk/typescript/cryptography' + - '!sdk/typescript/faucet' + - '!sdk/typescript/transactions' + - '!sdk/typescript/client' + - '!sdk/typescript/verify' + - '!sdk/typescript/multisig' + - '!sdk/typescript/utils' diff --git a/prettier.config.js b/prettier.config.js index 432c29d05b6f0..b9870d5747ae7 100644 --- a/prettier.config.js +++ b/prettier.config.js @@ -16,5 +16,11 @@ module.exports = { tailwindConfig: './apps/explorer/tailwind.config.ts', }, }, + { + files: 'sdk/**/*', + options: { + proseWrap: 'always', + }, + }, ], }; diff --git a/sdk/bcs/README.md b/sdk/bcs/README.md index 0b2cd075b252e..e3cf3cf511261 100644 --- a/sdk/bcs/README.md +++ b/sdk/bcs/README.md @@ -1,10 +1,13 @@ # BCS - Binary Canonical Serialization -This small and lightweight library implements [Binary Canonical Serialization (BCS)](https://github.com/zefchain/bcs) in JavaScript, making BCS available in both Browser and NodeJS environments. +This small and lightweight library implements +[Binary Canonical Serialization (BCS)](https://github.com/zefchain/bcs) in JavaScript, making BCS +available in both Browser and NodeJS environments. ## Install -To install, add the [`@mysten/bcs`](https://www.npmjs.com/package/@mysten/bcs) package to your project: +To install, add the [`@mysten/bcs`](https://www.npmjs.com/package/@mysten/bcs) package to your +project: ```sh npm i @mysten/bcs @@ -45,11 +48,15 @@ console.log(data); ## Description -BCS defines the way the data is serialized, and the result contains no type information. To be able to serialize the data and later deserialize, a schema has to be created (based on the built-in primitives, such as `address` or `u64`). There's no tip in the serialized bytes on what they mean, so the receiving part needs to know how to treat it. +BCS defines the way the data is serialized, and the result contains no type information. To be able +to serialize the data and later deserialize, a schema has to be created (based on the built-in +primitives, such as `address` or `u64`). There's no tip in the serialized bytes on what they mean, +so the receiving part needs to know how to treat it. ## Configuration -BCS constructor is configurable for the target. The following parameters are available for custom configuration: +BCS constructor is configurable for the target. The following parameters are available for custom +configuration: | parameter | required | description | | ------------------- | -------- | ------------------------------------------------------------------------- | @@ -89,7 +96,8 @@ let bytes = bcs.ser('User', { name: 'Adam', age: '30' }).toString('base64'); console.log(bytes); ``` -For Sui Move there's already a pre-built configuration which can be used through the `getSuiMoveConfig()` call. +For Sui Move there's already a pre-built configuration which can be used through the +`getSuiMoveConfig()` call. ```ts // Example: Sui Move Config @@ -107,7 +115,8 @@ const res = bcs.de(['vector', BCS.U8], ser); console.assert(res.toString() === val.toString()); ``` -Similar configuration exists for Rust, the difference is the `Vec` for vectors and `address` (being a special Move type) is not needed: +Similar configuration exists for Rust, the difference is the `Vec` for vectors and `address` +(being a special Move type) is not needed: ```ts // Example: Rust Config @@ -123,9 +132,11 @@ console.assert(res.toString() === val.toString()); ## Built-in types -By default, BCS will have a set of built-in type definitions and handy abstractions; all of them are supported in Move. +By default, BCS will have a set of built-in type definitions and handy abstractions; all of them are +supported in Move. -Supported integer types are: u8, u16, u32, u64, u128 and u256. Constants `BCS.U8` to `BCS.U256` are provided by the library. +Supported integer types are: u8, u16, u32, u64, u128 and u256. Constants `BCS.U8` to `BCS.U256` are +provided by the library. | Type | Constant | Description | | --------------------------- | ----------------------------- | ------------------------------------------------------ | @@ -210,7 +221,8 @@ console.assert((str1 == str2) == (str3 == str4), 'Result is the same'); ### Alias -Alias is a way to create custom name for a registered type. It is helpful for fine-tuning a predefined schema without making changes deep in the tree. +Alias is a way to create custom name for a registered type. It is helpful for fine-tuning a +predefined schema without making changes deep in the tree. ```ts // Example: Alias @@ -230,7 +242,8 @@ let _hex = bcs.ser('ObjectDigest', 'C0FFEE').toBytes(); ### Struct -Structs are the most common way of working with data; in BCS, a struct is simply a sequence of base types. +Structs are the most common way of working with data; in BCS, a struct is simply a sequence of base +types. ```ts // Example: Struct @@ -262,7 +275,8 @@ let _bytes = bcs ## Using Generics -To define a generic struct or an enum, pass the type parameters. It can either be done as a part of a string or as an Array. See below: +To define a generic struct or an enum, pass the type parameters. It can either be done as a part of +a string or as an Array. See below: ```ts // Example: Generics @@ -307,7 +321,9 @@ bcs.ser(['VecMap', BCS.STRING, BCS.STRING], { ### Enum -In BCS enums are encoded in a special way - first byte marks the order and then the value. Enum is an object, only one property of which is used; if an invariant is empty, `null` should be used to mark it (see `Option` below). +In BCS enums are encoded in a special way - first byte marks the order and then the value. Enum is +an object, only one property of which is used; if an invariant is empty, `null` should be used to +mark it (see `Option` below). ```ts // Example: Enum @@ -349,9 +365,11 @@ let _optionTxBatch = bcs.ser('Option', { ### Inline (de)serialization -Sometimes it is useful to get a value without registering a new struct. For that inline struct definition can be used. +Sometimes it is useful to get a value without registering a new struct. For that inline struct +definition can be used. -> Nested struct definitions are not yet supported, only first level properties can be used (but they can reference any type, including other struct types). +> Nested struct definitions are not yet supported, only first level properties can be used (but they +> can reference any type, including other struct types). ```ts // Example: Inline Struct @@ -382,7 +400,8 @@ Currently, main applications of this library are: 2. Deserializing onchain data for performance and formatting reasons 3. Deserializing events -In this library, all of the primitive Move types are present as built-ins, however, there's a set of special types in Sui which can be simplified to a primitive. +In this library, all of the primitive Move types are present as built-ins, however, there's a set of +special types in Sui which can be simplified to a primitive. ```rust // Definition in Move which we want to read in JS @@ -430,9 +449,7 @@ struct UID has store { id: ID } -struct ID has store, copy, drop { -bytes: address -} +struct ID has store, copy, drop { bytes: address } // { id: { bytes: '0x.....' } } diff --git a/sdk/docs/.prettierignore b/sdk/docs/.prettierignore new file mode 100644 index 0000000000000..9c74a639a2d0b --- /dev/null +++ b/sdk/docs/.prettierignore @@ -0,0 +1,2 @@ +CHANGELOG.md +.next diff --git a/sdk/docs/next.config.js b/sdk/docs/next.config.js new file mode 100644 index 0000000000000..851d1e52ec37a --- /dev/null +++ b/sdk/docs/next.config.js @@ -0,0 +1,9 @@ +// Copyright (c) Mysten Labs, Inc. +// SPDX-License-Identifier: Apache-2.0 + +const withNextra = require('nextra')({ + theme: 'nextra-theme-docs', + themeConfig: './theme.config.jsx', +}); + +module.exports = withNextra(); diff --git a/sdk/docs/package.json b/sdk/docs/package.json new file mode 100644 index 0000000000000..5084cf3bdad41 --- /dev/null +++ b/sdk/docs/package.json @@ -0,0 +1,31 @@ +{ + "name": "@mysten/sdk-docs", + "version": "1.0.0", + "description": "Docs for @mysten npm packages", + "main": "index.js", + "scripts": { + "dev": "next dev", + "build": "next build", + "start": "next start", + "prettier:check": "prettier -c --ignore-unknown .", + "prettier:fix": "prettier -w --ignore-unknown .", + "eslint:check": "eslint --max-warnings=0 .", + "eslint:fix": "pnpm run eslint:check --fix", + "lint": "pnpm run eslint:check && pnpm run prettier:check", + "lint:fix": "pnpm run eslint:fix && pnpm run prettier:fix" + }, + "publishConfig": { + "access": "restricted" + }, + "keywords": [], + "author": "Mysten Labs ", + "license": "Apache-2.0", + "dependencies": { + "@types/node": "^20.4.2", + "next": "^13.4.10", + "nextra": "^2.10.0", + "nextra-theme-docs": "^2.10.0", + "react": "^18.2.0", + "react-dom": "^18.2.0" + } +} diff --git a/sdk/docs/pages/_meta.json b/sdk/docs/pages/_meta.json new file mode 100644 index 0000000000000..7b3fcbbd2ce19 --- /dev/null +++ b/sdk/docs/pages/_meta.json @@ -0,0 +1,13 @@ +{ + "index": { + "title": "Home" + }, + "typescript-sdk": { + "title": "TypeScript SDK", + "type": "page" + }, + "wallet-kit": { + "title": "Wallet Kit", + "type": "page" + } +} diff --git a/sdk/docs/pages/index.mdx b/sdk/docs/pages/index.mdx new file mode 100644 index 0000000000000..cf739174949c3 --- /dev/null +++ b/sdk/docs/pages/index.mdx @@ -0,0 +1,8 @@ +import { Cards, Card } from 'nextra/components'; + +# Sui Typescript Documentation + + + + + diff --git a/sdk/docs/pages/typescript-sdk/_meta.json b/sdk/docs/pages/typescript-sdk/_meta.json new file mode 100644 index 0000000000000..6e88ebd6220bd --- /dev/null +++ b/sdk/docs/pages/typescript-sdk/_meta.json @@ -0,0 +1,7 @@ +{ + "index": "Typescript SDK", + "faucet": "Faucet", + "sui-client": "SuiClient", + "transaction-building": "Transaction Building", + "cryptography": "Cryptography" +} diff --git a/sdk/docs/pages/typescript-sdk/cryptography/_meta.json b/sdk/docs/pages/typescript-sdk/cryptography/_meta.json new file mode 100644 index 0000000000000..46c56ae985e81 --- /dev/null +++ b/sdk/docs/pages/typescript-sdk/cryptography/_meta.json @@ -0,0 +1,5 @@ +{ + "keypairs": "KeyPairs", + "multisig": "Multisig", + "mnemonics": "Mnemonics" +} diff --git a/sdk/docs/pages/typescript-sdk/cryptography/keypairs.mdx b/sdk/docs/pages/typescript-sdk/cryptography/keypairs.mdx new file mode 100644 index 0000000000000..44a6f9ca82039 --- /dev/null +++ b/sdk/docs/pages/typescript-sdk/cryptography/keypairs.mdx @@ -0,0 +1,7 @@ +import { Callout } from 'nextra/components'; + +# KeyPairs + + + Coming soon! + diff --git a/sdk/docs/pages/typescript-sdk/cryptography/mnemonics.mdx b/sdk/docs/pages/typescript-sdk/cryptography/mnemonics.mdx new file mode 100644 index 0000000000000..1a7257e31172c --- /dev/null +++ b/sdk/docs/pages/typescript-sdk/cryptography/mnemonics.mdx @@ -0,0 +1,7 @@ +import { Callout } from 'nextra/components'; + +# Mnemonics + + + Coming soon! + diff --git a/sdk/docs/pages/typescript-sdk/cryptography/multisig.mdx b/sdk/docs/pages/typescript-sdk/cryptography/multisig.mdx new file mode 100644 index 0000000000000..5a24a3ec773b8 --- /dev/null +++ b/sdk/docs/pages/typescript-sdk/cryptography/multisig.mdx @@ -0,0 +1,7 @@ +import { Callout } from 'nextra/components'; + +# MultiSig + + + Coming soon! + diff --git a/sdk/docs/pages/typescript-sdk/faucet.mdx b/sdk/docs/pages/typescript-sdk/faucet.mdx new file mode 100644 index 0000000000000..f73822bfb23c7 --- /dev/null +++ b/sdk/docs/pages/typescript-sdk/faucet.mdx @@ -0,0 +1,21 @@ +import { Callout } from 'nextra/components'; + +# Faucet + +To get started with the SDK it can be helpful get some Sui tokens to play with. The faucet is a +simple way to get some tokens sent to your address in `testnet`, `devnet` or `localnet` if you are +running your own network locally for development. + +You can request sui from the faucet using the `@mysten/sui.js/faucet` package. + +```typescript +import { requestSuiFromFaucetV0, getFaucetHost } from '@mysten/sui.js/faucet'; + +await requestSuiFromFaucetV0({ + host: getFaucetHost('testnet'), + recipient: '0xcc2bd176a478baea9a0de7a24cd927661cc6e860d5bacecb9a138ef20dbab231', +}); +``` + +The sui faucet is rate limited, so after making this call you may not be able to request more sui +for a while. The exact limits depend on which network you are connecting to. diff --git a/sdk/docs/pages/typescript-sdk/index.mdx b/sdk/docs/pages/typescript-sdk/index.mdx new file mode 100644 index 0000000000000..2d897a7ca7699 --- /dev/null +++ b/sdk/docs/pages/typescript-sdk/index.mdx @@ -0,0 +1,29 @@ +import { Callout } from 'nextra/components'; + +# Getting Started + +The Sui Typescript SDK is a modular library of tool for interacting with the SUi blockchain. It can +be used to send queries to RPC nodes, build and sign transactions, and more. + +## Installation + +```sh npm2yarn +npm i -D @mysten/sui.js +``` + +## Overview + +The SDK is split into a set of modular packages that can be used independently or together. So you +can import just what you need. + +- [`@mysten/sui.js/client`](/typescript-sdk/sui-client) - A client for interacting with Sui RPC + nodes. +- [`@mysten/sui.js/transaction`](/typescript-sdk/transaction-building/basics) - Utilities for + building and interacting with transactions. +- [`@mysten/sui.js/keypairs/*`](/typescript-sdk/cryptography/keypairs) - Modular exports for + specific KeyPair implementations. +- `@mysten/sui.js/verify` - Methods for verifying transactions and messages. +- `@mysten/sui.js/cryptography` - Shared types and classes for cryptography. +- `@mysten/sui.js/multisig` - Utilities for working with multisig signatures. +- `@mysten/sui.js/utils` - Utilities for formatting and parsing various Sui types. +- [`@mysten/sui.js/faucet`](/typescript-sdk/faucet) - Methods for requesting sui from a faucet. diff --git a/sdk/docs/pages/typescript-sdk/sui-client.mdx b/sdk/docs/pages/typescript-sdk/sui-client.mdx new file mode 100644 index 0000000000000..4db9b2d44b7c8 --- /dev/null +++ b/sdk/docs/pages/typescript-sdk/sui-client.mdx @@ -0,0 +1,113 @@ +# SuiClient + +The `SuiClient` can be imported from `@mysten/sui.js/client` and is used to make RPC request to the +Sui network. + +## Usage + +```typescript +import { SuiClient, getFullnodeUrl } from '@mysten/sui.js/client'; + +// create a client connected to devnet +const client = new SuiClient({ url: getFullnodeUrl('devnet') }); + +// get coins owned by an address +await client.getCoins({ + owner: '0xcc2bd176a478baea9a0de7a24cd927661cc6e860d5bacecb9a138ef20dbab231', +}); +``` + +the `getFullnodeUrl` helper provides a default fullName url that can be used for developing. In a +production application, you will likely want to manually define the URL of the RPC provider you want +to use in your application. + +## Manually calling unsupported RPC methods + +The `SuiClient` can be used to call any RPC method exposed by the node you are connecting to. The +Client has built in methods for most RPC methods, but if there are methods missing, they can still +be called manually using the `call` method of the `SuiClient`. + +```typescript +import { SuiClient, getFullnodeUrl } from '@mysten/sui.js/client'; + +const client = new SuiClient({ url: getFullnodeUrl('devnet') }); +const committeeInfo = await client.call('suix_getCommitteeInfo', []); +``` + +For a full list of available RPC methods see the +[RPC documentation](https://docs.sui.io/sui-jsonrpc). + +## Subscribing to events + +In addition to calling RPC methods, the `SuiClient` also supports a few methods for subscribing to +events: + +```typescript +import { SuiClient, getFullnodeUrl } from '@mysten/sui.js/client'; + +const client = new SuiClient({ + url: getFullnodeUrl('testnet'), +}); + +const unsubscribe = await client.subscribeEvent({ + filter: { + Sender: '0xcc2bd176a478baea9a0de7a24cd927661cc6e860d5bacecb9a138ef20dbab231', + }, + onMessage(event) { + // handle subscription notification message here. This function is called once per subscription message. + }, +}); + +// later, to unsubscribe: +await unsubscribe(); +``` + +## Subscribing to transactions + +Similar to subscribing to events, the `SuiClient` also supports subscribing to transactions: + +```typescript +import { SuiClient, getFullnodeUrl } from '@mysten/sui.js/client'; + +const client = new SuiClient({ + url: getFullnodeUrl('testnet'), +}); + +const unsubscribe = await client.subscribeTransaction({ + filter: { + FromAddress: '0xcc2bd176a478baea9a0de7a24cd927661cc6e860d5bacecb9a138ef20dbab231', + }, + onMessage(event) { + // This function is called once per transaction. + }, +}); + +// later, to unsubscribe: +await unsubscribe(); +``` + +## Customizing the Transport + +The `SuiClient` uses a `Transport` class to manage connections to the RPC node. The default +`SuiHTTPTransport` makes both JSON RPC requests, as well as websocket requests for subscriptions. +You can construct a custom transport instance if you need to pass any custom options, such as +headers or timeout values. + +```typescript +import { SuiClient, SuiHTTPTransport, getFullnodeUrl } from '@mysten/sui.js/client'; + +const client = new SuiClient({ + transport: new SuiHTTPTransport({ + url: 'https://my-custom-node.com/rpc', + websocket: { + reconnectTimeout: 1000, + url: 'https://my-custom-node.com/websockets', + }, + rpc: { + headers: { + 'x-custom-header': 'custom value', + }, + }, + }), +}); +``` diff --git a/sdk/docs/pages/typescript-sdk/transaction-building/_meta.json b/sdk/docs/pages/typescript-sdk/transaction-building/_meta.json new file mode 100644 index 0000000000000..5344de98ba9d4 --- /dev/null +++ b/sdk/docs/pages/typescript-sdk/transaction-building/_meta.json @@ -0,0 +1,5 @@ +{ + "basics": "Basics", + "pure-arguments": "Pure Arguments", + "encoding-values": "Encoding Values" +} diff --git a/sdk/docs/pages/typescript-sdk/transaction-building/basics.mdx b/sdk/docs/pages/typescript-sdk/transaction-building/basics.mdx new file mode 100644 index 0000000000000..3bfe7b374b8e1 --- /dev/null +++ b/sdk/docs/pages/typescript-sdk/transaction-building/basics.mdx @@ -0,0 +1,7 @@ +import { Callout } from 'nextra/components'; + +# Basics + + + Coming soon! + diff --git a/sdk/docs/pages/typescript-sdk/transaction-building/encoding-values.mdx b/sdk/docs/pages/typescript-sdk/transaction-building/encoding-values.mdx new file mode 100644 index 0000000000000..e4c0787845b65 --- /dev/null +++ b/sdk/docs/pages/typescript-sdk/transaction-building/encoding-values.mdx @@ -0,0 +1,7 @@ +import { Callout } from 'nextra/components'; + +# Encoding Values + + + Coming soon! + diff --git a/sdk/docs/pages/typescript-sdk/transaction-building/pure-arguments.mdx b/sdk/docs/pages/typescript-sdk/transaction-building/pure-arguments.mdx new file mode 100644 index 0000000000000..93add77008602 --- /dev/null +++ b/sdk/docs/pages/typescript-sdk/transaction-building/pure-arguments.mdx @@ -0,0 +1,7 @@ +import { Callout } from 'nextra/components'; + +# Pure Values + + + Coming soon! + diff --git a/sdk/docs/pages/wallet-kit/_meta.json b/sdk/docs/pages/wallet-kit/_meta.json new file mode 100644 index 0000000000000..959fa90bc7c12 --- /dev/null +++ b/sdk/docs/pages/wallet-kit/_meta.json @@ -0,0 +1,3 @@ +{ + "index": "Wallet Kit" +} diff --git a/sdk/docs/pages/wallet-kit/index.mdx b/sdk/docs/pages/wallet-kit/index.mdx new file mode 100644 index 0000000000000..bd78270ede95c --- /dev/null +++ b/sdk/docs/pages/wallet-kit/index.mdx @@ -0,0 +1,7 @@ +import { Callout } from 'nextra/components'; + +# Getting Started + + + Coming soon! + diff --git a/sdk/docs/theme.config.jsx b/sdk/docs/theme.config.jsx new file mode 100644 index 0000000000000..cda982721d58b --- /dev/null +++ b/sdk/docs/theme.config.jsx @@ -0,0 +1,11 @@ +// Copyright (c) Mysten Labs, Inc. +// SPDX-License-Identifier: Apache-2.0 + +const config = { + logo: Sui Typescript Docs, + project: { + link: 'https://github.com/MystenLabs/sui/tree/main/sdk/typescript', + }, +}; + +export default config; diff --git a/sdk/docs/tsconfig.json b/sdk/docs/tsconfig.json new file mode 100644 index 0000000000000..67c8f153447ad --- /dev/null +++ b/sdk/docs/tsconfig.json @@ -0,0 +1,19 @@ +{ + "compilerOptions": { + "lib": ["dom", "dom.iterable", "esnext"], + "allowJs": true, + "skipLibCheck": true, + "strict": true, + "forceConsistentCasingInFileNames": true, + "noEmit": true, + "incremental": true, + "esModuleInterop": true, + "module": "esnext", + "moduleResolution": "node", + "resolveJsonModule": true, + "isolatedModules": true, + "jsx": "preserve" + }, + "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"], + "exclude": ["node_modules"] +} diff --git a/sdk/kiosk/README.md b/sdk/kiosk/README.md index 6c0e7612f39a6..3692136ee7c84 100644 --- a/sdk/kiosk/README.md +++ b/sdk/kiosk/README.md @@ -1,9 +1,10 @@ # Kiosk SDK -> **This package is still in active development. Use at your own risk**. -> Currently, the only supported environment is **Sui Testnet**. +> **This package is still in active development. Use at your own risk**. Currently, the only +> supported environment is **Sui Testnet**. -This Kiosk SDK library provides different utilities to interact/create/manage a [Kiosk](https://github.com/MystenLabs/sui/tree/main/kiosk). +This Kiosk SDK library provides different utilities to interact/create/manage a +[Kiosk](https://github.com/MystenLabs/sui/tree/main/kiosk). ## Installation diff --git a/sdk/ledgerjs-hw-app-sui/README.md b/sdk/ledgerjs-hw-app-sui/README.md index 06e9caffe40c6..27e251e7cbbb6 100644 --- a/sdk/ledgerjs-hw-app-sui/README.md +++ b/sdk/ledgerjs-hw-app-sui/README.md @@ -4,7 +4,8 @@ # ledgerjs-hw-app-sui -[Ledger Hardware Wallet](https://www.ledger.com/) JavaScript bindings for [Sui](https://sui.io/), based on [LedgerJS](https://github.com/LedgerHQ/ledgerjs). +[Ledger Hardware Wallet](https://www.ledger.com/) JavaScript bindings for [Sui](https://sui.io/), +based on [LedgerJS](https://github.com/LedgerHQ/ledgerjs). ## Using LedgerJS for Sui @@ -58,7 +59,9 @@ doAll().catch((err) => console.log(err)); ### Parameters - `transport` **`Transport`** -- `scrambleKey` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** (optional, default `"Sui"`) +- `scrambleKey` + **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** + (optional, default `"Sui"`) ### Examples @@ -75,8 +78,12 @@ Gets the Sui address for a given BIP-32 path. #### Parameters -- `path` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** a path in BIP-32 format -- `displayOnDevice` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** whether or not to display the address on the Ledger device. +- `path` + **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** a + path in BIP-32 format +- `displayOnDevice` + **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** + whether or not to display the address on the Ledger device. #### Examples @@ -84,7 +91,9 @@ Gets the Sui address for a given BIP-32 path. const publicKey = await sui.getPublicKey("44'/784'/0'/0'/0'"); ``` -Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>** an object with a public key. +Returns +**[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>** +an object with a public key. ### signTransaction @@ -92,7 +101,9 @@ Sign a transaction with a given BIP-32 path. #### Parameters -- `path` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** a path in BIP-32 format +- `path` + **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** a + path in BIP-32 format #### Examples @@ -100,7 +111,9 @@ Sign a transaction with a given BIP-32 path. const publicKey = await sui.signTransaction("44'/784'/0'/0'/0'", ''); ``` -Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>** an object with text field containing a signature. +Returns +**[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>** +an object with text field containing a signature. ### getVersion @@ -122,4 +135,6 @@ for version 0.1.0, it produces something like } ``` -Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<{[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)}>** an object with major, minor, and patch of the version. +Returns +**[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<{[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)}>** +an object with major, minor, and patch of the version. diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md index fc3f35ff895df..b0c0447aeb825 100644 --- a/sdk/typescript/README.md +++ b/sdk/typescript/README.md @@ -1,12 +1,20 @@ # Sui TypeScript SDK -This is the Sui TypeScript SDK built on the Sui [JSON RPC API](https://github.com/MystenLabs/sui/blob/main/doc/src/build/json-rpc.md). It provides utility classes and functions for applications to sign transactions and interact with the Sui network. +This is the Sui TypeScript SDK built on the Sui +[JSON RPC API](https://github.com/MystenLabs/sui/blob/main/doc/src/build/json-rpc.md). It provides +utility classes and functions for applications to sign transactions and interact with the Sui +network. -WARNING: Note that we are still iterating on the RPC and SDK API before TestNet, therefore please expect frequent breaking changes in the short-term. We expect the API to stabilize after the upcoming TestNet launch. +WARNING: Note that we are still iterating on the RPC and SDK API before TestNet, therefore please +expect frequent breaking changes in the short-term. We expect the API to stabilize after the +upcoming TestNet launch. ## Working with DevNet -The SDK will be published to [npm registry](https://www.npmjs.com/package/@mysten/sui.js) with the same bi-weekly release cycle as the DevNet validators and [RPC Server](https://github.com/MystenLabs/sui/blob/main/doc/src/build/json-rpc.md). To use the SDK in your project, you can do: +The SDK will be published to [npm registry](https://www.npmjs.com/package/@mysten/sui.js) with the +same bi-weekly release cycle as the DevNet validators and +[RPC Server](https://github.com/MystenLabs/sui/blob/main/doc/src/build/json-rpc.md). To use the SDK +in your project, you can do: ```bash $ npm install @mysten/sui.js @@ -16,13 +24,17 @@ You can also use your preferred npm client, such as yarn or pnpm. ## Working with local network -Note that the `latest` tag for the [published SDK](https://www.npmjs.com/package/@mysten/sui.js) might go out of sync with the RPC server on the `main` branch until the next release. If you're developing against a local network, we recommend using the `experimental`-tagged packages, which contain the latest changes from `main`. +Note that the `latest` tag for the [published SDK](https://www.npmjs.com/package/@mysten/sui.js) +might go out of sync with the RPC server on the `main` branch until the next release. If you're +developing against a local network, we recommend using the `experimental`-tagged packages, which +contain the latest changes from `main`. ```bash npm install @mysten/sui.js@experimental ``` -Refer to the [JSON RPC](https://github.com/MystenLabs/sui/blob/main/doc/src/build/json-rpc.md) topic for instructions about how to start a local network and local RPC server. +Refer to the [JSON RPC](https://github.com/MystenLabs/sui/blob/main/doc/src/build/json-rpc.md) topic +for instructions about how to start a local network and local RPC server. ## Building Locally @@ -35,13 +47,18 @@ $ pnpm install $ pnpm sdk build ``` -> All `pnpm` commands are intended to be run in the root of the Sui repo. You can also run them within the `sdk/typescript` directory, and remove change `pnpm sdk` to just `pnpm` when running commands. +> All `pnpm` commands are intended to be run in the root of the Sui repo. You can also run them +> within the `sdk/typescript` directory, and remove change `pnpm sdk` to just `pnpm` when running +> commands. ## Type Doc -You can view the generated [Type Doc](https://typedoc.org/) for the [current release of the SDK](https://www.npmjs.com/package/@mysten/sui.js) at http://typescript-sdk-docs.s3-website-us-east-1.amazonaws.com/. +You can view the generated [Type Doc](https://typedoc.org/) for the +[current release of the SDK](https://www.npmjs.com/package/@mysten/sui.js) at +http://typescript-sdk-docs.s3-website-us-east-1.amazonaws.com/. -For the latest docs for the `main` branch, run `pnpm doc` and open the [doc/index.html](doc/index.html) in your browser. +For the latest docs for the `main` branch, run `pnpm doc` and open the +[doc/index.html](doc/index.html) in your browser. ## Testing @@ -65,9 +82,13 @@ npx vitest txn-builder.test.ts Troubleshooting: -If you see errors like `ECONNRESET or "socket hang up"`, run `node -v` to make sure your node version is `v18.x.x`. Refer to this [guide](https://blog.logrocket.com/how-switch-node-js-versions-nvm/) to switch node version. +If you see errors like `ECONNRESET or "socket hang up"`, run `node -v` to make sure your node +version is `v18.x.x`. Refer to this +[guide](https://blog.logrocket.com/how-switch-node-js-versions-nvm/) to switch node version. -Some more follow up here is if you used homebrew to install node, there could be multiple paths to node on your machine. https://stackoverflow.com/questions/52676244/node-version-not-updating-after-nvm-use-on-mac +Some more follow up here is if you used homebrew to install node, there could be multiple paths to +node on your machine. +https://stackoverflow.com/questions/52676244/node-version-not-updating-after-nvm-use-on-mac To run E2E tests against DevNet @@ -77,7 +98,8 @@ VITE_FAUCET_URL='https://faucet.devnet.sui.io:443/gas' VITE_FULLNODE_URL='https: ## Connecting to Sui Network -The `SuiClient` class provides a connection to the JSON-RPC Server and should be used for all read-only operations. The default URLs to connect with the RPC server are: +The `SuiClient` class provides a connection to the JSON-RPC Server and should be used for all +read-only operations. The default URLs to connect with the RPC server are: - local: http://127.0.0.1:9000 - DevNet: https://fullnode.devnet.sui.io @@ -94,7 +116,9 @@ await client.getCoins({ }); ``` -For local development, you can run `cargo run --bin sui-test-validator` to spin up a local network with a local validator, a fullnode, and a faucet server. Refer to [this guide](https://docs.sui.io/build/sui-local-network) for more information. +For local development, you can run `cargo run --bin sui-test-validator` to spin up a local network +with a local validator, a fullnode, and a faucet server. Refer to +[this guide](https://docs.sui.io/build/sui-local-network) for more information. ```typescript import { SuiClient, getFullnodeUrl } from '@mysten/sui.js/client'; @@ -131,7 +155,6 @@ You can request sui from the faucet when running against devnet, testnet, or loc ```typescript import { requestSuiFromFaucetV0, getFaucetHost } from '@mysten/sui.js/faucet'; -// get coins owned by an address await requestSuiFromFaucetV0({ host: getFaucetHost('testnet'), recipient: '0xcc2bd176a478baea9a0de7a24cd927661cc6e860d5bacecb9a138ef20dbab231', @@ -140,7 +163,8 @@ await requestSuiFromFaucetV0({ ## Writing APIs -For a primer for building transactions, refer to [this guide](https://docs.sui.io/build/prog-trans-ts-sdk). +For a primer for building transactions, refer to +[this guide](https://docs.sui.io/build/prog-trans-ts-sdk). ### Transfer Object @@ -273,7 +297,8 @@ console.log({ result }); ### Get Owned Objects -Fetch objects owned by the address `0xcc2bd176a478baea9a0de7a24cd927661cc6e860d5bacecb9a138ef20dbab231` +Fetch objects owned by the address +`0xcc2bd176a478baea9a0de7a24cd927661cc6e860d5bacecb9a138ef20dbab231` ```typescript import { SuiClient, getFullnodeUrl } from '@mysten/sui.js/client'; @@ -287,7 +312,8 @@ const objects = await client.getOwnedObjects({ ### Get Object -Fetch object details for the object with id `0xe19739da1a701eadc21683c5b127e62b553e833e8a15a4f292f4f48b4afea3f2` +Fetch object details for the object with id +`0xe19739da1a701eadc21683c5b127e62b553e833e8a15a4f292f4f48b4afea3f2` ```typescript import { SuiClient, getFullnodeUrl } from '@mysten/sui.js/client'; @@ -379,7 +405,8 @@ client.getCheckpoint({ id: '1994010' }).then(function (checkpoint: Checkpoint) { ### Get Coins -Fetch coins of type `0x65b0553a591d7b13376e03a408e112c706dc0909a79080c810b93b06f922c458::usdc::USDC` owned by an address: +Fetch coins of type `0x65b0553a591d7b13376e03a408e112c706dc0909a79080c810b93b06f922c458::usdc::USDC` +owned by an address: ```typescript import { SuiClient, getFullnodeUrl } from '@mysten/sui.js/client'; @@ -438,7 +465,8 @@ const events = client.queryEvents({ }); ``` -Subscribe to all events created by transactions sent by account `0xcc2bd176a478baea9a0de7a24cd927661cc6e860d5bacecb9a138ef20dbab231` +Subscribe to all events created by transactions sent by account +`0xcc2bd176a478baea9a0de7a24cd927661cc6e860d5bacecb9a138ef20dbab231` ```typescript import { SuiClient, getFullnodeUrl } from '@mysten/sui.js/client'; diff --git a/sdk/wallet-adapter/README.md b/sdk/wallet-adapter/README.md index 996a6c9d1806c..0fd37e564f0dc 100644 --- a/sdk/wallet-adapter/README.md +++ b/sdk/wallet-adapter/README.md @@ -1,11 +1,16 @@ # Sui Wallet Adapter -> **⚠️ These packages are experimental and will change rapidly as they are being developed. Do not consider these APIs to be stable. If you have any feedback, [open an issue](https://github.com/MystenLabs/sui/issues/new/choose) or message us on [Discord](https://discord.gg/Sui).** +> **⚠️ These packages are experimental and will change rapidly as they are being developed. Do not +> consider these APIs to be stable. If you have any feedback, +> [open an issue](https://github.com/MystenLabs/sui/issues/new/choose) or message us on +> [Discord](https://discord.gg/Sui).** Sui Wallet Adapter is a set of libraries that makes it easy to connect your dApp to Sui wallets. ## Getting started -We recommend using [Sui Wallet Kit](./wallet-kit/README.md) for connecting to wallets from React applications. +We recommend using [Sui Wallet Kit](./wallet-kit/README.md) for connecting to wallets from React +applications. -If you're not using React, you can use the underlying [wallet adapter packages](./adapters/) to determine which wallets are currently available in the dApp, and interact with the wallets. +If you're not using React, you can use the underlying [wallet adapter packages](./adapters/) to +determine which wallets are currently available in the dApp, and interact with the wallets. diff --git a/sdk/wallet-adapter/adapters/unsafe-burner/README.md b/sdk/wallet-adapter/adapters/unsafe-burner/README.md index 1086c9d56d8db..187fe7369a4bf 100644 --- a/sdk/wallet-adapter/adapters/unsafe-burner/README.md +++ b/sdk/wallet-adapter/adapters/unsafe-burner/README.md @@ -1,5 +1,6 @@ # `@mysten/wallet-adapter-unsafe-burner` -This adapter uses an unsafe local keypair to sign transactions. It can be used during development to easily test wallet signing flows without requiring additional user input. +This adapter uses an unsafe local keypair to sign transactions. It can be used during development to +easily test wallet signing flows without requiring additional user input. This adapter should never be used in production. diff --git a/sdk/wallet-adapter/example/src/README.md b/sdk/wallet-adapter/example/src/README.md index 9c86d8d4d581b..59fcc44e20a31 100644 --- a/sdk/wallet-adapter/example/src/README.md +++ b/sdk/wallet-adapter/example/src/README.md @@ -1,3 +1,4 @@ #### Wallet Adapter Example -This folder contains an example React frontend that utilizes the Sui Wallet Adapter. You can view the Wallet Adapter source code in the /wallet-adapter/packages folder. +This folder contains an example React frontend that utilizes the Sui Wallet Adapter. You can view +the Wallet Adapter source code in the /wallet-adapter/packages folder. diff --git a/sdk/wallet-adapter/wallet-kit/README.md b/sdk/wallet-adapter/wallet-kit/README.md index 3b0e37071ab3f..f2780e24229e3 100644 --- a/sdk/wallet-adapter/wallet-kit/README.md +++ b/sdk/wallet-adapter/wallet-kit/README.md @@ -1,8 +1,12 @@ # Sui Wallet Kit -> **⚠️ These packages are experimental and will change rapidly as they are being developed. Do not consider these APIs to be stable. If you have any feedback, [open an issue](https://github.com/MystenLabs/sui/issues/new/choose) or message us on [Discord](https://discord.gg/Sui).** +> **⚠️ These packages are experimental and will change rapidly as they are being developed. Do not +> consider these APIs to be stable. If you have any feedback, +> [open an issue](https://github.com/MystenLabs/sui/issues/new/choose) or message us on +> [Discord](https://discord.gg/Sui).** -Sui Wallet Kit is a library that makes it easy to connect your dApp to Sui wallets. It wraps the underlying Sui Wallet Adapters and comes pre-configured with sane defaults. +Sui Wallet Kit is a library that makes it easy to connect your dApp to Sui wallets. It wraps the +underlying Sui Wallet Adapters and comes pre-configured with sane defaults. ## Getting started @@ -22,7 +26,8 @@ export function App() { } ``` -> The `WalletKitProvider` also supports an `adapters` prop, which lets you override the default Sui Wallet Adapters. +> The `WalletKitProvider` also supports an `adapters` prop, which lets you override the default Sui +> Wallet Adapters. You can then add a **Connect Wallet** button to your page: @@ -41,7 +46,8 @@ function ConnectToWallet() { } ``` -To get access to the currently connected wallet, use the `useWalletKit()` hook to interact with the wallet, such as proposing transactions: +To get access to the currently connected wallet, use the `useWalletKit()` hook to interact with the +wallet, such as proposing transactions: ```tsx import { TransactionBlock } from '@mysten/sui.js/transactions'; @@ -75,12 +81,18 @@ export function SendTransaction() { ### Usage without React -We do not currently have non-React UI libraries for connecting to wallets. The wallet adapters and logic in the React library (`@mysten/wallet-adapter-react`) can be used as reference for implementing a wallet connection UI in other UI libraries. +We do not currently have non-React UI libraries for connecting to wallets. The wallet adapters and +logic in the React library (`@mysten/wallet-adapter-react`) can be used as reference for +implementing a wallet connection UI in other UI libraries. ## Supported wallets -Wallet Kit comes pre-configured with every supported wallet. You can also install individual wallet adapters that you plan on using in your project. +Wallet Kit comes pre-configured with every supported wallet. You can also install individual wallet +adapters that you plan on using in your project. ### Wallet Standard -The `WalletStandardAdapterProvider` adapter (published under `@mysten/wallet-adapter-wallet-standard`) automatically supports wallets that adhere to the cross-chain [Wallet Standard](https://github.com/wallet-standard/wallet-standard/). This adapter detects the available wallets in users' browsers. You do not need to configure additional adapters. +The `WalletStandardAdapterProvider` adapter (published under +`@mysten/wallet-adapter-wallet-standard`) automatically supports wallets that adhere to the +cross-chain [Wallet Standard](https://github.com/wallet-standard/wallet-standard/). This adapter +detects the available wallets in users' browsers. You do not need to configure additional adapters. diff --git a/sdk/wallet-adapter/wallet-standard/README.md b/sdk/wallet-adapter/wallet-standard/README.md index ada699c1cc7af..a2b2627e03cb2 100644 --- a/sdk/wallet-adapter/wallet-standard/README.md +++ b/sdk/wallet-adapter/wallet-standard/README.md @@ -1,12 +1,14 @@ # `@mysten/wallet-standard` -A suite of standard utilities for implementing wallets and libraries based on the [Wallet Standard](https://github.com/wallet-standard/wallet-standard/). +A suite of standard utilities for implementing wallets and libraries based on the +[Wallet Standard](https://github.com/wallet-standard/wallet-standard/). ## Implementing the Wallet Standard in an extension wallet ### Creating a wallet interface -You need to create a class that represents your wallet. You can use the `Wallet` interface from `@mysten/wallet-standard` to help ensure your class adheres to the standard. +You need to create a class that represents your wallet. You can use the `Wallet` interface from +`@mysten/wallet-standard` to help ensure your class adheres to the standard. ```typescript import { Wallet, SUI_DEVNET_CHAIN } from '@mysten/wallet-standard'; @@ -32,12 +34,17 @@ class YourWallet implements Wallet { ### Implementing features -Features are standard methods consumers can use to interact with a wallet. To be listed in the Sui wallet adapter, you must implement the following features in your wallet: +Features are standard methods consumers can use to interact with a wallet. To be listed in the Sui +wallet adapter, you must implement the following features in your wallet: - `standard:connect` - Used to initiate a connection to the wallet. -- `standard:events` - Used to listen for changes that happen within the wallet, such as accounts being added or removed. -- `sui:signTransactionBlock` - Used to prompt the user to sign a transaction block, and return the serializated transaction block and signature back to the user. This method does not submit the transaction block for execution. -- `sui:signAndExecuteTransactionBlock` - Used to prompt the user to sign a transaction block, then submit it for execution to the blockchain. +- `standard:events` - Used to listen for changes that happen within the wallet, such as accounts + being added or removed. +- `sui:signTransactionBlock` - Used to prompt the user to sign a transaction block, and return the + serializated transaction block and signature back to the user. This method does not submit the + transaction block for execution. +- `sui:signAndExecuteTransactionBlock` - Used to prompt the user to sign a transaction block, then + submit it for execution to the blockchain. You can implement these features in your wallet class under the `features` property: @@ -102,9 +109,12 @@ class YourWallet implements Wallet { ### Exposing accounts -The last requirement of the wallet interface is to expose an `acccounts` interface. This should expose all of the accounts that a connected dapp has access to. It can be empty prior to initiating a connection through the `standard:connect` feature. +The last requirement of the wallet interface is to expose an `acccounts` interface. This should +expose all of the accounts that a connected dapp has access to. It can be empty prior to initiating +a connection through the `standard:connect` feature. -The accounts can use the `ReadonlyWalletAccount` class to easily construct an account matching the required interface. +The accounts can use the `ReadonlyWalletAccount` class to easily construct an account matching the +required interface. ```typescript import { ReadonlyWalletAccount } from '@mysten/wallet-standard'; @@ -131,7 +141,8 @@ class YourWallet implements Wallet { ### Registering in the window -Once you have a compatible interface for your wallet, you can register it using the `registerWallet` function. +Once you have a compatible interface for your wallet, you can register it using the `registerWallet` +function. ```typescript import { registerWallet } from '@mysten/wallet-standard'; @@ -139,4 +150,5 @@ import { registerWallet } from '@mysten/wallet-standard'; registerWallet(new YourWallet()); ``` -> If you're interested in the internal implementation of the `registerWallet` method, you can [see how it works here](https://github.com/wallet-standard/wallet-standard/blob/b4794e761de688906827829d5380b24cb8ed5fd5/packages/core/wallet/src/register.ts#L9). +> If you're interested in the internal implementation of the `registerWallet` method, you can +> [see how it works here](https://github.com/wallet-standard/wallet-standard/blob/b4794e761de688906827829d5380b24cb8ed5fd5/packages/core/wallet/src/register.ts#L9).