Blockchain as a Service:JS SDK getting started

Prerequisites

Before you begin, ensure that you have:

• Node.js above v10 and below v16 — download from nodejs.org

• A contract blockchain instance in the BaaS platform

• The JS SDK package (alipay-mychain-0.2.27.tgz) — see JS SDK introduction for download instructions

Step 1: Install the SDK

In your project directory, run:

npm i alipay-mychain-0.2.27.tgz --save

Step 2: Prepare SSL certificates

Three certificate files are required to establish a TLS connection to the blockchain node.

If you haven't applied for certificates yet, follow the Access the Blockchain section in Quick Experience for Free to generate all three files.

Step 3: Prepare a blockchain account

Each transaction on the contract blockchain must be signed by an existing account. The SDK needs the account's account name and its private key file.

Create an account in the BaaS platform. During account creation, specify the account name, public key, and recovery public key. The user.key file corresponds to the account's public key and serves as the private key file.

Convert user.key to PEM format so the SDK can read it:

openssl ec -in user.key -passin pass:${key_password} -passout pass:${key_password} -aes256 -out user.pem

Replace ${key_password} with your private key password.

Step 4: Connect and verify

The following example initializes a connection to the blockchain and calls QueryLastBlock to confirm the connection is working.

const Chain = require("@alipay/mychain/index.node") // Node.js environment
const fs = require("fs")

// Load the account private key
const accountKey = fs.readFileSync("./certs/user.pem", { encoding: "utf8" })
const accountPassword = "<your-pem-password>"  // Replace with your user.pem password

const keyInfo = Chain.utils.getKeyInfo(accountKey, accountPassword)
// keyInfo.privateKey and keyInfo.publicKey are hexadecimal strings

// Load SSL certificates and configure the connection
const passphrase = "<your-client-key-password>"  // Replace with your client.key password
const opt = {
  host: "<node-ip>",        // IP address of the target blockchain node
  port: 18130,              // Port number of the blockchain node
  timeout: 30000,           // Connection timeout in milliseconds
  cert: fs.readFileSync("./certs/client.crt", { encoding: "utf8" }),
  ca: fs.readFileSync("./certs/ca.crt", { encoding: "utf8" }),
  key: fs.readFileSync("./certs/client.key", { encoding: "utf8" }),
  userPublicKey: keyInfo.publicKey,
  userPrivateKey: keyInfo.privateKey,
  userRecoverPublicKey: keyInfo.publicKey,
  userRecoverPrivateKey: keyInfo.privateKey,
  passphrase: passphrase
}

// Initialize the connection
const chain = Chain(opt)

// Verify the connection by querying the latest block
chain.ctr.QueryLastBlock({}, (err, data) => {
  console.log('raw data:', data)
  console.log('block hash:', data.block.block_header.hash)
  console.log('block number:', data.block.block_header.block_number)
})

Replace the following placeholders before running:

A successful response looks like:

raw data: { msg_type: 58,
  sequence: 1,
  return_code: 0,
  group_id: '0x0000000000000000000000000000000000000000',
  block:
   { block_header:
      { hash:
         '0xe99d8958a45e8c87a7b10efc259828f06fe083995be52997f5d310f2b6d073a6',
        version: 2,
        block_number: 84265,
        parent_hash:
         '0x918b263a8e6c6fff594b89570970ef4bef24cf93aeed5347f7b250b070857c4b',
        transaction_root:
         '0x0000000000000000000000000000000000000000000000000000000000000000',
        receipt_root:
         '0x0000000000000000000000000000000000000000000000000000000000000000',
        state_root:
         '0x9f71cb9ce960e5637bad6da5be8daa2d7e557942208f241a60589b2de98e6c71',
        gas_used: 0,
        timestamp: 1547382477852,
        log_bloom:
         '0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000' },
     block_body:
      { transaction_list: [],
        receipt_list: [],
        consensus_proof:
         '0xf8f2f8c9b8419746989382c1613c6c3ce98bf79ac92a8d69952c22f4064194869c53b4075d517cfc98eda861212687e49b186c08d196770bd356762fa2a88d0288c0556f271a01b84138a97446a75c76a31d24880c343407bd7bc24608685c494240ac603cad62201a01a423718661b24e517ee6f6b2fee6d356b57833305860700cca81b0238f870400b841eaf508392d9098a3e7fb46f6f7aa4b53311e5a0d13e300d02025af7453ea130a6c27407c1da254578cae80ed498d4807587883f837c1716b0be8ae02cf955d6000e61e83014929a0e200d8bee723d820022d5c5a1f8fe6b521c0a4fff0b5ec03a7c6061276d68b58' } },
  api: 'QueryLastBlock' }
block hash: 0xe99d8958a45e8c87a7b10efc259828f06fe083995be52997f5d310f2b6d073a6
block number: 84265

The response includes a return_code field. A value of 0 means the call succeeded; any other value is an error code. The result field in the transaction receipt works in the same way. See Error codes for details.

SDK reference

// Node.js environment (TLS protocol)
const Chain = require("@alipay/mychain/index.node")

// Browser environment
const Chain = require("@alipay/mychain")

What's next

• Submit your first transaction — see the JS SDK API reference for available operations

• Handle errors — check Error codes for the full list of return_code values and their meanings

• Explore the full SDK — see JS SDK introduction for advanced usage and all supported operations