Advanced Installation and Usage

This document outlines all available methods to install and use Telescope.

Telescope CLI

Install Telescope globally:

npm install -g @cosmology/telescope

Generate a Package

Use the interactive prompt:

telescope generate

Or specify options directly:

telescope generate --access public --userfullname "Your Name" --useremail "your@email.com" --module-desc "Your module description" --username "your-username" --license MIT --module-name "your-module" --chain-name cosmos --use-npm-scoped

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

Download Protocol Buffers

Basic usage:

telescope download

With a config file:

telescope download --config ./protod.config.json --out ./git-modules

protod.config.json example:

{
  "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": true,
  "tempRepoDir": "git-modules",
  "targets": [
    "cosmos/**/*.proto",
    "cosmwasm/**/*.proto",
    "ibc/**/*.proto",
  ]
}

From a specific repository:

telescope download --git-repo owner/repository --targets cosmos/auth/v1beta1/auth.proto

Transpile Proto Files

With default options:

telescope transpile

With custom configuration:

telescope transpile --config telescope-config.json

telescope-config.json exmaple:

{
    "protoDirs": [
        "./protos/"
    ],
    "outPath": "./codegen/",
    "options": {
        "classesUseArrowFunctions": true,
        "env": "v-next",
        "useInterchainJs": true,
        "useSDKTypes": false,
        "prototypes": {
            "enableRegistryLoader": false,
            "enableMessageComposer": false,
            "enabled": true,
            "parser": {
                "keepCase": false
            },
            "methods": {
                "fromJSON": false,
                "toJSON": false,
                "encode": true,
                "decode": true,
                "fromPartial": true,
                "toAmino": true,
                "fromAmino": true,
                "fromProto": false,
                "toProto": false,
                "fromProtoMsg": false,
                "toProtoMsg": false,
                "toAminoMsg": true,
                "fromAminoMsg": true
            },
            "addTypeUrlToDecoders": false,
            "addTypeUrlToObjects": true,
            "addAminoTypeToObjects": true,
            "typingsFormat": {
                "duration": "duration",
                "timestamp": "date",
                "useExact": false,
                "useDeepPartial": true,
                "num64": "bigint",
                "customTypes": {
                    "useCosmosSDKDec": true,
                    "useEnhancedDecimal": false
                },
                "useTelescopeGeneratedType": true,
                "autoFixUndefinedEnumDefault": true
            }
        },
        "bundle": {
            "enabled": false
        },
        "stargateClients": {
            "enabled": false
        },
        "lcdClients": {
            "enabled": false
        },
        "rpcClients": {
            "enabled": false
        },
        "helperFunctions": {
            "enabled": true,
            "useGlobalDecoderRegistry": true,
            "hooks": {
              "react": true,
              "vue": false
            }
        },
        "interfaces": {
            "enabled": true,
            "useGlobalDecoderRegistry": true,
            "registerAllDecodersToGlobal": false,
            "useUnionTypes": true
        },
        "aminoEncoding": {
            "enabled": true,
            "useLegacyInlineEncoding": false,
            "disableMsgTypes": false,
            "useProtoOptionality": true,
            "customTypes": {
              "useCosmosSDKDec": true
            }
        }
    }
}

Create Interchain App (CIA)

Install CIA globally:

npm install -g create-interchain-app

Create a new project with the Telescope boilerplate:

cia --boilerplate telescope

Navigate to your project directory:

cd ./your-project/packages/your-module
yarn install

Download protos and generate code:

yarn download-protos
yarn codegen

Create Cosmos App (CCA)

Install CCA globally:

npm install -g create-cosmos-app

Create a new package with the Telescope boilerplate:

cca --boilerplate telescope

Navigate to your package directory:

cd ./your-project/packages/telescope
yarn install

Download protos and generate code:

telescope download --config ./your.config.json
yarn codegen

Manual Installation

Add Telescope to your project:

yarn add --dev @cosmology/telescope

Install required dependencies:

yarn add @cosmjs/amino @cosmjs/proto-signing @cosmjs/stargate @cosmjs/tendermint-rpc

Use either the programmatic API or the CLI with npm/yarn prefixes:

yarn telescope generate
npx telescope download

Programmatic Usage

First, add Telescope and dependencies:

yarn add --dev @cosmology/telescope
yarn add @cosmjs/amino @cosmjs/proto-signing @cosmjs/stargate @cosmjs/tendermint-rpc

Downloading Protos Programmatically

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);
  });

Generating Code Programmatically

import { join } from 'path';
import telescope from '@cosmology/telescope';
import { sync as rimraf } from 'rimraf';
 
// Define input and output paths
const protoDirs = [join(__dirname, '/../proto')];
const outPath = join(__dirname, '../src');
rimraf(outPath);
 
// Run Telescope with options
telescope({
  protoDirs,
  outPath,
  
  // all options are totally optional
  options: {
    aminoEncoding: {
      enabled: true
    },
    lcdClients: {
      enabled: false
    },
    rpcClients: {
      enabled: false,
      camelCase: true
    },
    
    // Package-specific options
    packages: {
      nebula: {
        prototypes: {
          typingsFormat: {
            useExact: false
          }
        }
      },
      akash: {
        stargateClients: {
          enabled: true,
          includeCosmosDefaultTypes: false
        },
        prototypes: {
          typingsFormat: {
            useExact: false
          }
        }
      }
    }
  }
}).then(() => {
  console.log('✨ all done!');
}).catch(e => {
  console.error(e);
  process.exit(1);
});

Example: Build Script Integration

// scripts/codegen.js
import { join } from 'path';
import telescope from '@cosmology/telescope';
import { sync as rimraf } from 'rimraf';
 
const protoDirs = [join(__dirname, '/../proto')];
const outPath = join(__dirname, '../src/generated');
rimraf(outPath);
 
telescope({
  protoDirs,
  outPath,
  options: {
    tsDisable: {
      disableAll: false,
      patterns: ['**/amino/**']
    },
    eslintDisable: {
      patterns: ['**/tx.amino.ts']
    },
    prototypes: {
      includePackageVar: true,
      typingsFormat: {
        useDeepPartial: true,
        timestamp: 'date',
        duration: 'duration'
      }
    }
  }
}).then(() => {
  console.log('✨ Code generation complete');
});

titles Broadcasting Messages