@casper-ecosystem/odra-js-client

JavaScript/TypeScript utilities for interacting with Odra smart contracts on the Casper Network.

Built on top of casper-js-sdk.

Installation

npm install @casper-ecosystem/odra-js-client casper-js-sdk

Quick start

import { OdraClient } from '@casper-ecosystem/odra-js-client';
import { Args, CLValue } from 'casper-js-sdk';
import { readFileSync } from 'fs';

const client = new OdraClient(
  'http://<Node Address>:7777/rpc',
  'casper-test'
);

client.setContractHash(
  '834d3e29...', // bare hex, "contract-hash-...", or "hash-..." all accepted
  'f1127fd1...', // contract package hash (required for write operations)
);

// Read a Var<T> field
const name = await client.getVar('name');
console.log(name?.toString()); // e.g. "MyToken"

// Read a Mapping<K, V> entry
const balance = await client.getMappingItem('balances', 'account-hash-abc...');

// Call a non-payable entry point
await client.call(
  'transfer',
  Args.fromMap({
    recipient: CLValue.newCLString('account-hash-...'),
    amount: CLValue.newCLUInt256('1000000000'),
  }),
  {
    sender: publicKey,
    paymentAmount: '2500000000',
    signingKeys: [privateKey],
  },
);

// Call a payable entry point via the Odra proxy WASM
const proxyWasm = new Uint8Array(readFileSync('proxy_caller.wasm'));

await client.callPayable(
  'stake',
  Args.fromMap({}),
  '2000000000000', // amount in motes
  proxyWasm,
  {
    sender: publicKey,
    paymentAmount: '5000000000',
    signingKeys: [privateKey],
  },
);

API

OdraClient

High-level client. Wraps all utilities into a single class.

| Method | Description | | ---------------------------------------------------------- | -------------------------------------------------------------------------------- | | setContractHash(hash, packageHash?) | Configure target contract. Accepts bare hex or prefixed strings. Returns this. | | resolveContractHash() | Auto-resolve and cache the latest contract hash from the package hash. | | getNamedKeys() | List all named keys on the contract. | | getVar(name) | Read an Odra Var<T> field by named key name. | | getMappingItem(name, key) | Read one entry from an Odra Mapping<K,V> dictionary. | | getState(index, key?, blockHeight?) | Read raw bytes from Odra's internal state dictionary by field index. | | call(entryPoint, args, params) | Submit a non-payable contract call transaction. | | callPayable(entryPoint, innerArgs, amount, wasm, params) | Submit a payable call via the Odra proxy WASM pattern. |

OdraStateDecoder

Sequential byte-stream decoder for packed Odra struct state.

Odra stores every Var<T> / Mapping<K,V> value as Casper-serialised bytes inside a List<U8> CLValue. The decoder skips the 4-byte count prefix automatically.

Fields must be read in the same order they are declared in the Rust struct. Reading out of order will silently produce incorrect values.

import { getOdraState, OdraStateDecoder } from '@casper-ecosystem/odra-js-client';
import { RpcClient, HttpHandler } from 'casper-js-sdk';

const rpc = new RpcClient(new HttpHandler('http://<Node Address>:7777/rpc'));
const raw = await getOdraState(rpc, contractHash, BONDING_CURVE_INDEX, tokenKey);
const dec = new OdraStateDecoder(raw);

const csprReserve = dec.readU256();
const initialPrice = dec.readU256();
const graduated = dec.readBool();
const graduatedAt = dec.readOptionU64(); // bigint | null

| Method | CL type | Return | | -------------------- | -------------------- | ----------------------- | | readBool() | Bool | boolean | | readU8() | U8 | number | | readU32() | U32 | number | | readU64() | U64 | bigint | | readU128() | U128 | bigint | | readU256() | U256 | bigint | | readU512() | U512 | bigint | | readString() | String | string | | readKey() | Key | string (prefixed) | | readKeyBytes() | Key | Uint8Array (33 bytes) | | readOption(fn) | Option<T> | T \| null | | readOptionU64() | Option<U64> | bigint \| null | | readOptionU256() | Option<U256> | bigint \| null | | readOptionString() | Option<String> | string \| null | | readFixedBytes(n) | ByteArray(N) | Uint8Array | | readBytes() | Bytes / List<U8> | Uint8Array |

Proxy call utilities

import { isOdraProxyCall, parseOdraProxyCallArgs, buildOdraProxyCallArgs } from '@casper-ecosystem/odra-js-client';

// Detect an Odra proxy call in a transaction scanner
if (isOdraProxyCall(tx.payload.fields.args)) {
  const { packageHash, entryPoint, innerArgs, amount } = parseOdraProxyCallArgs(
    tx.payload.fields.args,
  );
}

// Build outer args for a proxy WASM transaction
const outerArgs = buildOdraProxyCallArgs(
  packageHashHex,
  'stake',
  innerArgs,
  '2000000000000', // omit for non-payable
);

Low-level state helpers

import {
  getOdraContractNamedKeys,
  getOdraContractVar,
  getOdraContractMappingItem,
  getOdraState,
  deriveOdraStateKey,
  getContractHashFromPackage,
} from '@casper-ecosystem/odra-js-client';

Payable entry points - how it works

Odra payable entry points require a Session transaction (inline WASM) instead of a standard contract call. This is because StoredVersionedContractByPackageHash cannot transfer CSPR from the caller's main purse to the contract's purse.

The proxy WASM accepts:

| Arg | CL type | Description | | ---------------- | --------------- | ---------------------------------------------------------- | | package_hash | ByteArray(32) | Target contract package hash | | entry_point | String | Entry point name | | args | List<U8> | Casper-serialised inner Args | | attached_value | U512 | Amount the contract reads via env().attached_value() | | amount | U512 | Amount the Casper node uses to perform the actual transfer |

amount and attached_value carry the same mote value but serve different purposes.

Development

npm install
npm test       # run unit tests
npm run build  # compile to dist/

License

Apache 2.0