Skip to content

Added new docs and learn based on Readme #772

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

Merged
Zetazzz merged 7 commits into from
May 27, 2025
Merged

Added new docs and learn based on Readme #772

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
664cf09
Added new docs and learn based on Readme
NorOldBurden May 15, 2025
d5fc1a3
Merge branch 'main' into add-docs-and-learn
NorOldBurden May 16, 2025
2cefd5f
Resolved conflict and updated file structure
NorOldBurden May 19, 2025
fab9ff6
Added cia boilerplate video to quickstart
NorOldBurden May 19, 2025
0db80ac
Removed legacy --config in readme and updated developing folder for l…
NorOldBurden May 19, 2025
12e7f90
Update docs related to quickstart
NorOldBurden May 21, 2025
c8e1f14
Reorganized install related readme, docs and learn
NorOldBurden May 23, 2025
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
243 changes: 134 additions & 109 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,179 +109,171 @@ The following blockchain libraries (generated by Telescope) are available via np

## Quickstart

Follow the instructions below to generate a new Typescript package that you can publish to npm.

First, install `telescope` and `create-cosmos-app`
Follow the instructions below to generate a new Typescript package that you can publish to npm. You can also follow the video: https://youtu.be/iQf6p65fbdY

`create-interchain-app`
```sh
npm install -g @cosmology/telescope create-cosmos-app
npm install -g create-interchain-app
```


### Generate

Use the [`create-cosmos-app`](https://github.com/hyperweb-io/create-cosmos-app/) command to create a new package from the `telescope` boilerplate.
Use the [`create-interchain-app`](https://github.com/hyperweb-io/create-interchain-app/) command to create a new package from the `telescope` boilerplate.

```sh
cca --boilerplate telescope
```
cia --boilerplate telescope

Then, you'll navigate into `./your-project/packages/telescope` package for the next steps.

You can also use `telescope generate` command to generate package according to the prompt or terminal command params such as:
`telescope generate --access public --userfullname testname --useremail [email protected] --module-desc test --username salkfl --license MIT --module-name test --chain-name cosmos --use-npm-scoped`

The available options are:
`--userfullname` `--useremail` `--module-desc` `--username` `--module-name` `--chain-name` `--access` `--use-npm-scoped` `--license`
Then, you'll navigate into `./your-project/packages/telescope` package for the next steps.

If some required options are missing, it will prompt to ask for the info.

To be noted, `--use-npm-scoped` only works when `--access` is `public`
For detailed cli `generate` commands, please check our docs and learn directories.

### Download protos with CLI
### Download protos

The old ` telescope install ` command has been deprecated

You can use our CLI to download protos by using `download` command.
You can use our script to download protos by using `download-protos`command in the boilerplate.

```sh
telescope download
yarn download-protos
```

You should now see some repos cloned in `./git-modules` and proto files generated in `./protos`. These are the proto files downloaded according to your config.

Examples:
For detailed cli `download` commands, please check our docs and learn directories.

```sh
# Telescope will do the download according to .json file of --config
# Telescope will put proto into location specified by --out
telescope download --config ./protod.config.json --out ./git-modules
```
### Transpile

To create the Typescript files for your chain, run the `yarn codegen` command inside of the package.

```sh
# Telescope download from target repo according to --git-repo
# in format of (i.e. <owner>/<repository> or <owner>/<repository>/<branch>)
# <branch> can be empty, it will use main as default
# Also --targets is required to specify the targets to download
# in format like cosmos/auth/v1beta1/auth.proto
telescope download --git-repo target-repo --targets target-proto
```
yarn codegen
```

### Build

Finally, run `install` and `build` to generate the JS and types for publishing your module to npm.

```sh
# ssh arg is optional, default is false
telescope download --config ./protod.config.json --out ./git-modules --ssh true
yarn build
```

### Publishing

```js
// .protod.config.json example
//
// `repos` are the repository it's going to clone
// in format of (i.e. { "owner": <owner>, "repo": <repo> } or { "owner": <owner>, "repo": <repo>, "branch": <branch> })
// <branch> can be empty, it will use main as default
//
// `protoDirMapping` is the directory of repo specified if the proto is not under repo's root directory ./protos
// in format of (i.e. <owner>/<repository> or <owner>/<repository>/<branch>)
// <branch> can be empty, it will use main as default
//
// `outDir` is where the output proto will be put
//
// `targets` are the target proto to download
// `targets` can be patterns like:
// "cosmos/bank/v1beta1/tx.proto",
// "cosmos/gov/**/*.proto",
// "cosmos/authz/**/*.proto",
{
"repos": [
{ "owner": "cosmos", "repo": "cosmos-sdk" },
...
],
"protoDirMapping": {
"gogo/protobuf/master": ".",
...
},
"outDir": "protos",
"ssh": true,
"tempRepoDir": "git-modules",
"targets": [
"cosmos/auth/v1beta1/auth.proto",
...
]
}
```
Now you should have code inside of your `./src` folder, ready for publshing. If you used the `create-interchain-app` boilerplate, use `lerna` to publish (and/or read the README in the boilerplate for instructions), or run `npm publish` from your repository.

### Transpile
# Usage

To create the Typescript files for your chain, run the `yarn codegen` command inside of the package.
## Advanced Install
The methods below are all the options you can use to install and use Telescope

### Telescope CLI
Install telescope
```sh
npm install -g @cosmology/telescope
```
yarn codegen
```
The steps by order are: generate, download and transpile.

### Transpile with CLI
1.Generate a package with the telescope CLI:

Less recommended, but you can also use our CLI for transpilation. To create the Typescript files with the `cli`, run the `transpile` command.
Use and follow the default prompt:
```sh
telescope generate
```

Or advanced cli option by your choice:
```sh
telescope transpile
telescope generate --access public --userfullname "Your Name" --useremail "[email protected]" --module-desc "Your module description" --username "your-username" --license MIT --module-name "your-module" --chain-name cosmos --use-npm-scoped
```

You should now see some `.ts` files generated in `./src`. These are the real source files used in your application.
Available options:
- `--userfullname`: Your full name
- `--useremail`: Your email
- `--module-desc`: Module description
- `--username`: GitHub username
- `--module-name`: Module name
- `--chain-name`: Chain name
- `--access`: Package access (`public` or `private`)
- `--use-npm-scoped`: Use npm scoped package (only works with `--access public`)
- `--license`: License type

2.Download protocol buffer files:
```sh
telescope download
```

Examples:
This will clone repositories into `./git-modules` and generate proto files in `./protos`.

Download with a config file:
```sh
# Telescope takes chain1 folder as input,
# and generate files in 'gen/src' folder.
telescope transpile --protoDirs ../../__fixtures__/chain1 --outPath gen/src
telescope download --config ./protod.config.json --out ./git-modules
```

Download from a specific repo:
```sh
# Telescope takes chain1 folder as input,
# and generate files in 'gen/src' folder using default telescope options.
telescope transpile --protoDirs ../../__fixtures__/chain1 --outPath gen/src --useDefaults
telescope download --git-repo owner/repository --targets cosmos/auth/v1beta1/auth.proto
```

3. Transpile (Generate TypeScript code from proto files):
Use default telescope option:
```sh
# Telescope takes chain1 folder(from args) and chain2 folder(from config) as input,
# and generate files in 'gen/src'(defined in the config file, will override outPath in args) folder using a config file.
# Note: --config will override --useDefaults.
telescope transpile --protoDirs ../../__fixtures__/chain1 --config .telescope.json
telescope transpile
```

Use customized telescope option:
```sh
# Telescope takes more than one config. The config afterward will override those in front. In this case values in .telescope-ext.json will override those in .telescope.json.
telescope transpile --config .telescope.json --config .telescope-ext.json
telescope transpile --config your-config.json
```

```js
//.telescope.json
{
"protoDirs": [
"../../fixtures/chain2"
],
"outPath": "gen/src",
"options": {
// telescope options
...
}
}
### CIA
Please follow the video: https://youtu.be/iQf6p65fbdY
Or [Go to Quickstart](#quickstart)

### CCA
First, install `create-cosmos-app`

```sh
npm install -g create-cosmos-app
```

### Build
Use the [`create-cosmos-app`](https://github.com/hyperweb-io/create-cosmos-app/) command to create a new package from the `telescope` boilerplate.

Finally, run `install` and `build` to generate the JS and types for publishing your module to npm.
```sh
cca --boilerplate telescope
```

Then, you'll navigate into `./your-project/packages/telescope` package for the next steps.

Install dependency and use cli to download the protos you want.
```sh
yarn build
yarn install
telescope download --config ./your.config.json
```

### Publishing
To create the Typescript files for your chain, run the `yarn codegen` command inside of the package.

Now you should have code inside of your `./src` folder, ready for publshing. If you used the `create-cosmos-app` boilerplate, use `lerna` to publish (and/or read the README in the boilerplate for instructions), or run `npm publish` from your repository.
```sh
yarn codegen
```

# Usage
### Manual install
If you want to use telescope in your own project.

## Programatic Usage
Run the command in ./your-project
```sh
yarn add --dev @cosmology/telescope
```
Install helpers and cosmjs [dependencies listed here](#dependencies)

We recommand to use [Go to Programatic Usage](#programatic-usage)

You can also use [Go to Telescope Cli](#telescope-cli)
To be noted for cli command, add 'npx' or 'yarn' prefix when you use it within your project. For instance: 'yarn telescope generate', 'npx telescope download', etc.

### Programatic Usage

First add telescope to your `devDependencies`:

Expand All @@ -291,6 +283,39 @@ yarn add --dev @cosmology/telescope

Install helpers and cosmjs [dependencies listed here](#dependencies)

Download command example:
```js
import downloadProtos from '@cosmology/telescope/main/commands/download'

const config = {
repos: [
{ owner: "cosmos", repo: "cosmos-sdk", branch: "release/v0.50.x" },
{ owner: "cosmos", repo: "ibc-go" },
],
protoDirMapping: {
"gogo/protobuf/master": ".",
"googleapis/googleapis/master": ".",
"protocolbuffers/protobuf/main": "src"
},
outDir: "protos",
ssh: false,
tempRepoDir: "git-modules",
targets: [
"cosmos/**/*.proto",
"ibc/**/*.proto",
]
};

downloadProtos(config)
.then(() => console.log('✅ Proto download completed'))
// @ts-ignore
.catch((error) => {
console.error('❌ Proto download failed:', error);
process.exit(1);
});
```

Transpile command example:
```js
import { join } from 'path';
import telescope from '@cosmology/telescope';
Expand Down Expand Up @@ -1365,7 +1390,7 @@ A unified toolkit for building applications and smart contracts in the Interchai
| **Wallet Connectors**| [**Interchain Kit**](https://github.com/hyperweb-io/interchain-kit)<sup>beta</sup>, [**Cosmos Kit**](https://github.com/hyperweb-io/cosmos-kit) | Experience the convenience of connecting with a variety of web3 wallets through a single, streamlined interface. |
| **Signing Clients** | [**InterchainJS**](https://github.com/hyperweb-io/interchainjs)<sup>beta</sup>, [**CosmJS**](https://github.com/cosmos/cosmjs) | A single, universal signing interface for any network |
| **SDK Clients** | [**Telescope**](https://github.com/hyperweb-io/telescope) | Your Frontend Companion for Building with TypeScript with Cosmos SDK Modules. |
| **Starter Kits** | [**Create Interchain App**](https://github.com/hyperweb-io/create-interchain-app)<sup>beta</sup>, [**Create Cosmos App**](https://github.com/hyperweb-io/create-cosmos-app) | Set up a modern Interchain app by running one command. |
| **Starter Kits** | [**Create Interchain App**](https://github.com/hyperweb-io/create-interchain-app)<sup>beta</sup> | Set up a modern Interchain app by running one command. |
| **UI Kits** | [**Interchain UI**](https://github.com/hyperweb-io/interchain-ui) | The Interchain Design System, empowering developers with a flexible, easy-to-use UI kit. |
| **Testing Frameworks** | [**Starship**](https://github.com/hyperweb-io/starship) | Unified Testing and Development for the Interchain. |
| **TypeScript Smart Contracts** | [**Create Hyperweb App**](https://github.com/hyperweb-io/create-hyperweb-app) | Build and deploy full-stack blockchain applications with TypeScript |
Expand Down
Loading
Loading