diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 000000000..b8ec00a1c --- /dev/null +++ b/.editorconfig @@ -0,0 +1,8 @@ +# This file adds LF and newline support at the end of files +# for many editors automatically including Github +root = true + +# Unix-style newlines with a newline ending every file +[*] +end_of_line = lf +insert_final_newline = true diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 000000000..27f2b4e6f --- /dev/null +++ b/.gitattributes @@ -0,0 +1,23 @@ +# Ensure that text files that any contributor introduces to the repository +# have their line endings normalized to LF +* text=auto eol=lf + +# All known text filetypes +*.cfg text eol=lf +*.Dockerfile text eol=lf +*.hcl text eol=lf +*.json text eol=lf +*.md text eol=lf +*.move text eol=lf +*.py text eol=lf +*.sh text eol=lf +*.tf text eol=lf +*.toml text eol=lf +*.txt text eol=lf +*.yaml text eol=lf +*.ts text eol=lf +*.js text eol=lf + +# Ensure that powerscript files are not auto-converted +*.ps1 binary + diff --git a/.github/actions/run-build/action.yaml b/.github/actions/run-build/action.yaml new file mode 100644 index 000000000..46eb8aa5e --- /dev/null +++ b/.github/actions/run-build/action.yaml @@ -0,0 +1,19 @@ +name: "Run optimized SDK build" +description: | + Run build for Browser, Node, and Types + +runs: + using: composite + steps: + # Install node and pnpm. + - uses: actions/setup-node@v3 + with: + node-version-file: .node-version + registry-url: "https://registry.npmjs.org" + - uses: pnpm/action-setup@v2 + with: + version: 8.9.0 + + # Run package install and build + - run: pnpm install --frozen-lockfile && pnpm build + shell: bash diff --git a/.github/actions/run-fmt/action.yaml b/.github/actions/run-fmt/action.yaml new file mode 100644 index 000000000..5501c25a8 --- /dev/null +++ b/.github/actions/run-fmt/action.yaml @@ -0,0 +1,19 @@ +name: "Verify SDK formatting" +description: | + Run prettier on the codebase to ensure consistency + +runs: + using: composite + steps: + # Install node and pnpm. + - uses: actions/setup-node@v3 + with: + node-version-file: .node-version + registry-url: "https://registry.npmjs.org" + - uses: pnpm/action-setup@v2 + with: + version: 8.9.0 + + # Verify that the format is correct + - run: pnpm install --frozen-lockfile && pnpm _fmt --check + shell: bash diff --git a/.github/actions/run-lint/action.yaml b/.github/actions/run-lint/action.yaml new file mode 100644 index 000000000..14da27d80 --- /dev/null +++ b/.github/actions/run-lint/action.yaml @@ -0,0 +1,19 @@ +name: "Lint SDK Code" +description: | + Run eslint on the codebase to ensure consistency + +runs: + using: composite + steps: + # Install node and pnpm. + - uses: actions/setup-node@v3 + with: + node-version-file: .node-version + registry-url: "https://registry.npmjs.org" + - uses: pnpm/action-setup@v2 + with: + version: 8.9.0 + + # Run eslint + - run: pnpm install --frozen-lockfile && pnpm lint + shell: bash diff --git a/.github/actions/run-unit-tests/action.yaml b/.github/actions/run-unit-tests/action.yaml new file mode 100644 index 000000000..4b1a07eb1 --- /dev/null +++ b/.github/actions/run-unit-tests/action.yaml @@ -0,0 +1,19 @@ +name: "SDK Unit Tests" +description: | + Run the SDK unit tests locally + +runs: + using: composite + steps: + # Install node and pnpm. + - uses: actions/setup-node@v3 + with: + node-version-file: .node-version + registry-url: "https://registry.npmjs.org" + - uses: pnpm/action-setup@v2 + with: + version: 8.9.0 + + # Run unit tests + - run: pnpm install --frozen-lockfile && pnpm unit-test + shell: bash diff --git a/.github/workflows/run-build.yaml b/.github/workflows/run-build.yaml new file mode 100644 index 000000000..e44715be2 --- /dev/null +++ b/.github/workflows/run-build.yaml @@ -0,0 +1,19 @@ +env: + GIT_SHA: ${{ github.event.pull_request.head.sha || github.sha }} + +name: "Run SDK optimized build" +on: + pull_request: + types: [labeled, opened, synchronize, reopened, auto_merge_enabled] + push: + branches: + - main + +jobs: + run-tests: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: + ref: ${{ env.GIT_SHA }} + - uses: ./.github/actions/run-build diff --git a/.github/workflows/run-fmt.yaml b/.github/workflows/run-fmt.yaml new file mode 100644 index 000000000..8cc34042c --- /dev/null +++ b/.github/workflows/run-fmt.yaml @@ -0,0 +1,19 @@ +env: + GIT_SHA: ${{ github.event.pull_request.head.sha || github.sha }} + +name: "Run SDK code format check" +on: + pull_request: + types: [labeled, opened, synchronize, reopened, auto_merge_enabled] + push: + branches: + - main + +jobs: + run-tests: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: + ref: ${{ env.GIT_SHA }} + - uses: ./.github/actions/run-fmt diff --git a/.github/workflows/run-lint.yaml b/.github/workflows/run-lint.yaml new file mode 100644 index 000000000..3fcee8f44 --- /dev/null +++ b/.github/workflows/run-lint.yaml @@ -0,0 +1,19 @@ +env: + GIT_SHA: ${{ github.event.pull_request.head.sha || github.sha }} + +name: "Run SDK code linting" +on: + pull_request: + types: [labeled, opened, synchronize, reopened, auto_merge_enabled] + push: + branches: + - main + +jobs: + run-tests: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: + ref: ${{ env.GIT_SHA }} + - uses: ./.github/actions/run-lint diff --git a/.github/workflows/run-unit-tests.yaml b/.github/workflows/run-unit-tests.yaml new file mode 100644 index 000000000..bf19ac94b --- /dev/null +++ b/.github/workflows/run-unit-tests.yaml @@ -0,0 +1,19 @@ +env: + GIT_SHA: ${{ github.event.pull_request.head.sha || github.sha }} + +name: "Run SDK unit tests" +on: + pull_request: + types: [labeled, opened, synchronize, reopened, auto_merge_enabled] + push: + branches: + - main + +jobs: + run-tests: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: + ref: ${{ env.GIT_SHA }} + - uses: ./.github/actions/run-unit-tests diff --git a/.prettierrc b/.prettierrc new file mode 100644 index 000000000..3773725ad --- /dev/null +++ b/.prettierrc @@ -0,0 +1,4 @@ +{ + "trailingComma": "all", + "printWidth": 120 +} diff --git a/CODEOWNERS b/CODEOWNERS new file mode 100644 index 000000000..82ed3aaec --- /dev/null +++ b/CODEOWNERS @@ -0,0 +1,7 @@ +# **Please** keep this file ordered alphabetically by directory paths. + +# Owners for the `.github` directory and all its subdirectories. +/.github/ @aptos-labs/developer-platform @aptos-labs/security + +# Auto-reviewers for all code +* @aptos-labs/developer-platform diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..8bc706b23 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,120 @@ +--- +id: contributing +title: Contributing to the Aptos TypeScript SDK +--- + +# Contributing + +Our goal is to make contributing to Aptos TypeScript SDK easy and transparent. See [Aptos Community](https://aptos.dev/community) +for full details. This page describes [our development process](#our-development-process). + +## Aptos SDK + +To contribute to the Aptos SDK implementation, first fork the [aptos-ts-sdk](https://github.com/aptos-labs/aptos-ts-sdk) +repository. For more information on how to fork see the [Github documentation](https://docs.github.com/en/get-started/quickstart/fork-a-repo). + +## Our Development Process +### Documentation + +Aptos's developer website is also open source (the code can be found in this +[repository](https://github.com/aptos-labs/aptos-core/tree/main/developers-docs-site/). It is built using +[Docusaurus](https://docusaurus.io/): + +If you know Markdown, you can already contribute! + +## Developer Workflow + +Changes to the project are proposed through pull requests. The general pull request workflow is as follows: + +* If you have added code that should be tested, add unit tests. +* If you have changed APIs, update the documentation. Make sure the documentation builds. +* Ensure all formatting applies with `pnpm fmt`. +* Ensure all tests and lints pass on each and every commit that is part of your pull request using `pnpm test && pnpm lint`. +* Submit your pull request. + +## Authoring Clean Commits + +### Logically Separate Commits + +Commits should be [atomic](https://en.wikipedia.org/wiki/Atomic_commit#Atomic_commit_convention) and broken down into +logically separate changes. Diffs should also be made easy for reviewers to read and review so formatting fixes or code +moves should not be included in commits with actual code changes. + +### Meaningful Commit Messages + +Commit messages are important and incredibly helpful for others when they dig through the commit history in order to +understand why a particular change was made and what problem it was intending to solve. For this reason commit messages +should be well written and conform with the following format: + +All commit messages should begin with a single short (50 character max) line summarizing the change and should skip the +full stop. This is the title of the commit. It is also preferred that this summary be prefixed with "[area]" where the +area is an identifier for the general area of the code being modified, e.g. + +``` +* [ci] enforce whitelist of nightly features +* [language] removing VerificationPass trait +``` + + +Following the commit title (unless it alone is self-explanatory), there should be a single blank line followed by the +commit body which includes more detailed, explanatory text as separate paragraph(s). It is recommended that the commit +body be wrapped at 72 characters so that Git has plenty of room to indent the text while still keeping everything under +80 characters overall. + +The commit body should provide a meaningful commit message, which: +* Explains the problem the change tries to solve, i.e. what is wrong with the current code without the change. +* Justifies the way the change solves the problem, i.e. why the result with the change is better. +* Alternative solutions considered but discarded, if any. + +### References in Commit Messages + +If you want to reference a previous commit in the history of the project, use the format "abbreviated sha1 (subject, +date)", with the subject enclosed in a pair of double-quotes, like this: + +```bash +Commit 895b53510 ("[consensus] remove slice_patterns feature", 2019-07-18) noticed that ... +``` + +This invocation of `git show` can be used to obtain this format: + +```bash +git show -s --date=short --pretty='format:%h ("%s", %ad)' +``` + +If a commit references an issue please add a reference to the body of your commit message, e.g. `issue #1234` or ` +fixes #456`. Using keywords like `fixes`, `resolves`, or `closes` will cause the corresponding issue to be closed when +the pull request is merged. + +Avoid adding any `@` mentions to commit messages, instead add them to the PR cover letter. + +## Responding to Reviewer Feedback + +During the review process a reviewer may ask you to make changes to your pull request. If a particular commit needs to +be changed, that commit should be amended directly. Changes in response to a review *should not* be made in separate +commits on top of your PR unless it logically makes sense to have separate, distinct commits for those changes. This +helps keep the commit history clean. + +If your pull request is out-of-date and needs to be updated because `main` has advanced, you should rebase your branch +on top of the latest main by doing the following: + +```bash +git fetch upstream +git checkout branch +git rebase -i upstream/main +``` + +You *should not* update your branch by merging the latest main into your branch. Merge commits included in PRs tend to +make it more difficult for the reviewer to understand the change being made, especially if the merge wasn't clean and +needed conflicts to be resolved. As such, PRs with merge commits will be rejected. + +## Bisect-able History + +It is important that the project history is bisect-able so that when regressions are identified we can easily use +`git bisect` to be able to pin-point the exact commit which introduced the regression. This requires that every commit +is able to be built and passes all lints and tests. So if your pull request includes multiple commits be sure that each +and every commit is able to be built and passes all checks performed by CI. + +## Issues + +The Aptos SDK uses [GitHub issues](https://github.com/aptos-labs/aptos-ts-sdk/issues) to track bugs. Please include +necessary information and instructions to reproduce your issue. diff --git a/LICENSE b/LICENSE index 261eeb9e9..a123aa874 100644 --- a/LICENSE +++ b/LICENSE @@ -186,14 +186,14 @@ same "printed page" as the copyright notice for easier identification within third-party archives. - Copyright [yyyy] [name of copyright owner] - Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + Copyright 2023 Aptos Foundation + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. diff --git a/README.md b/README.md index 5c44918f1..7834846c4 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,27 @@ -# SDK for Aptos Node API +# Typescript SDK for Aptos [![Discord][discord-image]][discord-url] [![NPM Package Version][npm-image-version]][npm-url] [![NPM Package Downloads][npm-image-downloads]][npm-url] -The Aptos TypeScript SDK provides a convenient way to interact with the Aptos blockchain using TypeScript. It offers a set of utility functions, classes, and types to simplify the integration process and enhance developer productivity. +The Aptos TypeScript SDK provides a convenient way to interact with the Aptos blockchain using TypeScript. It offers a +set of utility functions, classes, and types to simplify the integration process and enhance developer productivity. + +This repository supports version >= 2.0.0 of the [Aptos SDK npm package](https://www.npmjs.com/package/aptos). ## Installation ##### For use in Node.js or a web application -```ts -pnpm install aptos +Install with your favorite package manager such as npm, yarn, or pnpm: +```bash +npm install aptos ``` -You can also use your preferred npm client, such as yarn or npm. - ##### For use in a browser -```ts +You can add the SDK to your web application using a script tag: +```html