@talismn/sapi 0.0.0-pr1876-20250414012202

package/dist/talismn-sapi.esm.js

@@ -0,0 +1,529 @@
+import { assert, u8aConcatStrict } from '@polkadot/util';
+import { decodeMetadata, getLookupFn as getLookupFn$1, getDynamicBuilder } from '@talismn/scale';
+import anylogger from 'anylogger';
+import { Enum, Binary } from 'polkadot-api';
+import { getLookupFn } from '@polkadot-api/metadata-builders';
+import { toHex, mergeUint8 } from '@polkadot-api/utils';
+import { TypeRegistry, Metadata } from '@polkadot/types';
+import { merkleizeMetadata } from '@polkadot-api/merkleize-metadata';
+import { enhanceEncoder, Bytes, u16 } from '@polkadot-api/substrate-bindings';
+
+var packageJson = {
+	name: "@talismn/sapi"};
+
+var log = anylogger(packageJson.name);
+
+const getCallDocs = (chain, pallet, method) => {
+  try {
+    const typeIdCalls = chain.metadata.pallets.find(({
+      name
+    }) => name === pallet)?.calls;
+    if (!typeIdCalls) return null;
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let palletCalls = chain.metadata.lookup[typeIdCalls];
+    if (!palletCalls || palletCalls.id !== typeIdCalls) palletCalls = chain.metadata.lookup.find(v => v.id === typeIdCalls);
+    if (!palletCalls) return null;
+    const call = palletCalls.def.value.find(c => c.name === method);
+    return call?.docs?.join("\n") ?? null;
+  } catch (err) {
+    log.error("Failed to find call docs", {
+      pallet,
+      method,
+      chain
+    });
+    return null;
+  }
+};
+
+const getConstantValue = (chain, pallet, constant) => {
+  try {
+    const storageCodec = chain.builder.buildConstant(pallet, constant);
+    const encodedValue = chain.metadata.pallets.find(({
+      name
+    }) => name === pallet)?.constants.find(({
+      name
+    }) => name === constant)?.value;
+    if (!encodedValue) throw new Error(`Constant ${pallet}.${constant} not found`);
+    return storageCodec.dec(encodedValue);
+  } catch (err) {
+    log.error("Failed to get constant value", {
+      err,
+      chainId: chain.connector.chainId,
+      pallet,
+      constant
+    });
+    throw err;
+  }
+};
+
+const getChainInfo = chain => {
+  const {
+    spec_name: specName,
+    spec_version: specVersion,
+    transaction_version: transactionVersion
+  } = getConstantValue(chain, "System", "Version");
+  const base58Prefix = getConstantValue(chain, "System", "SS58Prefix");
+  return {
+    specName,
+    specVersion,
+    transactionVersion,
+    base58Prefix
+  };
+};
+
+const getDecodedCall = (palletName, methodName, args) => ({
+  type: palletName,
+  value: {
+    type: methodName,
+    value: args
+  }
+});
+const getDecodedCallFromPayload = (chain, payload) => {
+  const def = chain.builder.buildDefinition(chain.lookup.call);
+  const decoded = def.dec(payload.method);
+  return {
+    pallet: decoded.type,
+    method: decoded.value.type,
+    args: decoded.value.value
+  };
+};
+
+const getDispatchErrorMessage = (chain, err) => {
+  try {
+    if (!err) return null;
+    const error = err;
+    if (!error.type) throw new Error("Unknown dispatch error");
+    const lv1 = DISPATCH_ERROR[error.type];
+    if (!lv1) throw new Error("Unknown dispatch error");
+    if (lv1 === ERROR_METADATA_LOOKUP) return getModuleErrorMessage(chain, error.value);
+    if (typeof lv1 === "string") return lv1;
+    const lv2 = lv1[error.value?.type];
+    if (!lv2) throw new Error("Unknown dispatch error");
+    if (typeof lv2 === "string") return lv2;
+    throw new Error("Unknown dispatch error");
+  } catch (cause) {
+    log.error("Failed to parse runtime error", {
+      chainId: chain.connector.chainId,
+      cause,
+      err
+    });
+    return tryFormatError(err);
+  }
+};
+const ERROR_METADATA_LOOKUP = "METADATA_LOOKUP";
+
+// only `Module` errors are part of the metadata
+// errors below are defined as part of the runtime but their docs aren't included in the metadata
+// so those are copy/pasted from the polkadot-sdk repo
+
+// https://github.com/paritytech/polkadot-sdk/blob/56d97c3ad8c86e602bc7ac368751210517c4309f/substrate/primitives/runtime/src/lib.rs#L543
+const ERRORS_TRANSACTIONAL = {
+  LimitReached: "Too many transactional layers have been spawned",
+  NoLayer: "A transactional layer was expected, but does not exist"
+};
+
+// https://github.com/paritytech/polkadot-sdk/blob/56d97c3ad8c86e602bc7ac368751210517c4309f/substrate/primitives/runtime/src/lib.rs#L672
+const ERRORS_TOKEN = {
+  FundsUnavailable: "Funds are unavailable",
+  OnlyProvider: "Account that must exist would die",
+  BelowMinimum: "Account cannot exist with the funds that would be given",
+  CannotCreate: "Account cannot be created",
+  UnknownAsset: "The asset in question is unknown",
+  Frozen: "Funds exist but are frozen",
+  Unsupported: "Operation is not supported by the asset",
+  CannotCreateHold: "Account cannot be created for recording amount on hold",
+  NotExpendable: "Account that is desired to remain would die",
+  Blocked: "Account cannot receive the assets"
+};
+
+// https://github.com/paritytech/polkadot-sdk/blob/56d97c3ad8c86e602bc7ac368751210517c4309f/substrate/primitives/arithmetic/src/lib.rs#L76
+const ERRORS_ARITHMETIC = {
+  Overflow: "An underflow would occur",
+  Underflow: "An overflow would occur",
+  DivisionByZero: "Division by zero"
+};
+
+// https://github.com/paritytech/polkadot-sdk/blob/56d97c3ad8c86e602bc7ac368751210517c4309f/substrate/primitives/runtime/src/lib.rs#L714
+const DISPATCH_ERROR = {
+  CannotLookup: "Cannot lookup",
+  BadOrigin: "Bad origin",
+  Module: ERROR_METADATA_LOOKUP,
+  ConsumerRemaining: "Consumer remaining",
+  NoProviders: "No providers",
+  TooManyConsumers: "Too many consumers",
+  Token: ERRORS_TOKEN,
+  Arithmetic: ERRORS_ARITHMETIC,
+  Transactional: ERRORS_TRANSACTIONAL,
+  Exhausted: "Resources exhausted",
+  Corruption: "State corrupt",
+  Unavailable: "Resource unavailable",
+  RootNotAllowed: "Root not allowed",
+  Trie: "Unknown error",
+  // unsupported,
+  Other: "Unknown error" // unsupported,
+};
+const getModuleErrorMessage = (chain, error) => {
+  try {
+    if (!chain.metadata) throw new Error("Could not fetch metadata");
+    const pallet = chain.metadata.pallets.find(p => p.name === error.type);
+    if (typeof pallet?.errors !== "number") throw new Error("Unknown pallet");
+    const lookup = getLookupFn(chain.metadata);
+    const palletErrors = lookup(pallet.errors);
+    if (palletErrors.type !== "enum" || !palletErrors.innerDocs[error.value.type]?.length) throw new Error("Unknown error type");
+
+    // biome-ignore lint/style/noNonNullAssertion: <explanation>
+    return palletErrors.innerDocs[error.value.type].join(" ");
+  } catch (err) {
+    log.error("Failed to parse module error", {
+      chainId: chain.connector.chainId,
+      error,
+      err
+    });
+    return [error.type, error.value.type].join(": ");
+  }
+};
+const tryFormatError = err => {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const unsafeErr = err;
+    if (unsafeErr.type && unsafeErr.value?.type) return [unsafeErr.type, unsafeErr.value.type].join(": ");
+  } catch (err) {
+    // ignore
+  }
+  return "Unknown error";
+};
+
+const getSendRequestResult = (chain, method, params, isCacheable) => {
+  return chain.connector.send(method, params, isCacheable);
+};
+
+const getRuntimeCallResult = async (chain, apiName, method, args) => {
+  const call = chain.builder.buildRuntimeCall(apiName, method);
+  const hex = await getSendRequestResult(chain, "state_call", [`${apiName}_${method}`, toHex(call.args.enc(args))]);
+  return call.value.dec(hex);
+};
+
+const isApiAvailable = (chain, name, method) => {
+  return chain.metadata.apis.some(a => a.name === name && a.methods.some(m => m.name === method));
+};
+
+const getDryRunCall = async (chain, from, decodedCall) => {
+  log.log(`[sapi] getDryRun begin: ${Date.now()}`);
+  try {
+    if (!isApiAvailable(chain, "DryRunApi", "dry_run_call")) return {
+      available: false,
+      data: null
+    };
+    const origin = Enum("system", Enum("Signed", from));
+    const {
+      pallet,
+      method,
+      args
+    } = decodedCall;
+    const call = {
+      type: pallet,
+      value: {
+        type: method,
+        value: args
+      }
+    };
+
+    // This will throw an error if the api is not available on that chain
+    const data = await getRuntimeCallResult(chain, "DryRunApi", "dry_run_call", [origin, call]);
+    const ok = data.success && data.value.execution_result.success;
+    const errorMessage = data.success && !data.value.execution_result.success ? getDispatchErrorMessage(chain, data.value.execution_result.value.error) : null;
+    return {
+      available: true,
+      // NOTE: we can't re-export `@polkadot-api/descriptors` from this package.
+      // So, the caller of this function must pass in their own instance of `type DryRunResult` as the generic argument `T`.
+      data: data,
+      ok,
+      errorMessage
+    };
+  } catch (err) {
+    // Note : err is null if chain doesnt have the api
+    log.error("Failed to dry run", {
+      chainId: chain.connector.chainId,
+      err
+    });
+    return {
+      available: false,
+      data: null
+    };
+  } finally {
+    log.log(`[sapi] getDryRun end: ${Date.now()}`);
+  }
+};
+
+// used for chains that dont have metadata v15 yet
+const getExtrinsicDispatchInfo = async (chain, signedExtrinsic) => {
+  assert(signedExtrinsic.isSigned, "Extrinsic must be signed (or fakeSigned) in order to query fee");
+  const len = signedExtrinsic.registry.createType("u32", signedExtrinsic.encodedLength);
+  const dispatchInfo = await stateCall(chain.connector.send, "TransactionPaymentApi_query_info", "RuntimeDispatchInfo", [signedExtrinsic, len], undefined, true);
+  return {
+    partialFee: dispatchInfo.partialFee.toString()
+  };
+};
+const stateCall = async (request, method, resultType, args, blockHash, isCacheable) => {
+  // on a state call there are always arguments
+  const registry = args[0].registry;
+  const bytes = registry.createType("Raw", u8aConcatStrict(args.map(arg => arg.toU8a())));
+  const result = await request("state_call", [method, bytes.toHex(), blockHash], isCacheable);
+  return registry.createType(resultType, result);
+};
+
+const getTypeRegistry = (chain, payload) => {
+  log.log(`[sapi] getTypeRegistry begin: ${Date.now()}`);
+  const registry = new TypeRegistry();
+  if (chain.registryTypes) registry.register(chain.registryTypes);
+  const meta = new Metadata(registry, chain.hexMetadata);
+  registry.setMetadata(meta, payload.signedExtensions, chain.signedExtensions); // ~30ms
+
+  log.log(`[sapi] getTypeRegistry end: ${Date.now()}`);
+  return registry;
+};
+
+const getFeeEstimate = async (chain, payload, chainInfo) => {
+  // TODO do this without PJS / registry => waiting for @polkadot-api/tx-utils
+  const registry = getTypeRegistry(chain, payload);
+  const extrinsic = registry.createType("Extrinsic", payload);
+  extrinsic.signFake(payload.address, {
+    appId: 0,
+    nonce: payload.nonce,
+    blockHash: payload.blockHash,
+    genesisHash: payload.genesisHash,
+    runtimeVersion: {
+      specVersion: chainInfo.specVersion,
+      transactionVersion: chainInfo.transactionVersion
+      // other fields aren't necessary for signing
+    }
+  });
+  const bytes = extrinsic.toU8a(true);
+  const binary = Binary.fromBytes(bytes);
+  try {
+    const result = await getRuntimeCallResult(chain, "TransactionPaymentApi", "query_info", [binary, bytes.length]);
+    // Do not throw if partialFee is 0n. This is a valid response, eg: Bittensor remove_stake fee estimation is 0n.
+    if (!result?.partial_fee && result.partial_fee !== 0n) {
+      throw new Error("partialFee is not found");
+    }
+    return result.partial_fee;
+  } catch (err) {
+    log.error("Failed to get fee estimate using getRuntimeCallValue", {
+      err
+    });
+  }
+
+  // fallback to pjs encoded state call, in case the above fails (extracting runtime calls codecs might require metadata V15)
+  // Note: PAPI will consider TransactionPaymentApi as first class api so it should work even without V15, but this is not the case yet.
+  const {
+    partialFee
+  } = await getExtrinsicDispatchInfo(chain, extrinsic);
+  return BigInt(partialFee);
+};
+
+const getSapiConnector = ({
+  chainId,
+  send,
+  submit
+}) => ({
+  chainId,
+  send,
+  submit: (...args) => {
+    if (submit) return submit(...args);
+    throw new Error("submit handler not provided");
+  }
+});
+
+const getPayloadWithMetadataHash = (chain, chainInfo, payload) => {
+  if (!chain.hasCheckMetadataHash || !payload.signedExtensions.includes("CheckMetadataHash")) return {
+    payload,
+    txMetadata: undefined
+  };
+  try {
+    const {
+      decimals,
+      symbol: tokenSymbol
+    } = chain.token;
+    const {
+      base58Prefix,
+      specName,
+      specVersion
+    } = chainInfo;
+
+    // since ultimately this needs a V15 object, would be nice if this accepted one directly as input
+    const merkleizedMetadata = merkleizeMetadata(chain.hexMetadata, {
+      tokenSymbol,
+      decimals,
+      base58Prefix,
+      specName,
+      specVersion
+    });
+    const metadataHash = toHex(merkleizedMetadata.digest());
+    const payloadWithMetadataHash = {
+      ...payload,
+      mode: 1,
+      metadataHash,
+      withSignedTransaction: true
+    };
+
+    // TODO do this without PJS / registry => waiting for @polkadot-api/tx-utils
+    // const { extra, additionalSigned } = getSignedExtensionValues(payload, metadata)
+    // const badExtPayload = mergeUint8(fromHex(payload.method), ...extra, ...additionalSigned)
+
+    const registry = getTypeRegistry(chain, payload);
+    const extPayload = registry.createType("ExtrinsicPayload", payloadWithMetadataHash);
+    const barePayload = extPayload.toU8a(true);
+    const txMetadata = merkleizedMetadata.getProofForExtrinsicPayload(barePayload);
+    return {
+      payload: payloadWithMetadataHash,
+      txMetadata
+    };
+  } catch (err) {
+    log.error("Failed to get shortened metadata", {
+      error: err
+    });
+    return {
+      payload,
+      txMetadata: undefined
+    };
+  }
+};
+
+const getStorageValue = async (chain, pallet, entry, keys, at) => {
+  const storageCodec = chain.builder.buildStorage(pallet, entry);
+  const stateKey = storageCodec.keys.enc(...keys);
+  const hexValue = await getSendRequestResult(chain, "state_getStorage", [stateKey, at]);
+  if (!hexValue) return null; // caller will need to expect null when applicable
+
+  return storageCodec.value.dec(hexValue);
+};
+
+//////////////////////////////////////////////////////////////////////////////////////////////////////////////
+////////////////////////////                 Utilities from PAPI                 /////////////////////////////
+//////////////////////////////////////////////////////////////////////////////////////////////////////////////
+
+const toPjsHex = (value, minByteLen) => {
+  let inner = value.toString(16);
+  inner = (inner.length % 2 ? "0" : "") + inner;
+  const nPaddedBytes = Math.max(0, (minByteLen || 0) - inner.length / 2);
+  return "0x" + "00".repeat(nPaddedBytes) + inner;
+};
+const mortal = enhanceEncoder(Bytes(2).enc, value => {
+  const factor = Math.max(value.period >> 12, 1);
+  const left = Math.min(Math.max(trailingZeroes(value.period) - 1, 1), 15);
+  const right = value.phase / factor << 4;
+  return u16.enc(left | right);
+});
+function trailingZeroes(n) {
+  let i = 0;
+  while (!(n & 1)) {
+    i++;
+    n >>= 1;
+  }
+  return i;
+}
+
+const getSignerPayloadJSON = async (chain, palletName, methodName, args, signerConfig, chainInfo) => {
+  const {
+    codec,
+    location
+  } = chain.builder.buildCall(palletName, methodName);
+  const method = Binary.fromBytes(mergeUint8(new Uint8Array(location), codec.enc(args)));
+  const blockNumber = await getStorageValue(chain, "System", "Number", []);
+  if (blockNumber === null) throw new Error("Block number not found");
+  const [account, genesisHash, blockHash] = await Promise.all([
+  // TODO if V15 available, use a runtime call instead : AccountNonceApi/account_nonce
+  // about nonce https://github.com/paritytech/json-rpc-interface-spec/issues/156
+  getStorageValue(chain, "System", "Account", [signerConfig.address]), getStorageValue(chain, "System", "BlockHash", [0]), getSendRequestResult(chain, "chain_getBlockHash", [blockNumber], false) // TODO find the right way to fetch this with new RPC api, this is not available in storage yet
+  ]);
+  if (!genesisHash) throw new Error("Genesis hash not found");
+  if (!blockHash) throw new Error("Block hash not found");
+  const nonce = account ? account.nonce : 0;
+  const era = mortal({
+    period: 16,
+    phase: blockNumber % 16
+  });
+  const signedExtensions = chain.metadata.extrinsic.signedExtensions.map(ext => ext.identifier.toString());
+  const basePayload = {
+    address: signerConfig.address,
+    genesisHash: genesisHash.asHex(),
+    blockHash,
+    method: method.asHex(),
+    signedExtensions,
+    nonce: toPjsHex(nonce, 4),
+    specVersion: toPjsHex(chainInfo.specVersion, 4),
+    transactionVersion: toPjsHex(chainInfo.transactionVersion, 4),
+    blockNumber: toPjsHex(blockNumber, 4),
+    era: toHex(era),
+    tip: toPjsHex(0, 16),
+    // TODO gas station (required for Astar)
+    assetId: undefined,
+    version: 4
+  };
+  const {
+    payload,
+    txMetadata
+  } = getPayloadWithMetadataHash(chain, chainInfo, basePayload);
+
+  // Avail support
+  if (payload.signedExtensions.includes("CheckAppId")) payload.appId = 0;
+  log.log("[sapi] payload", {
+    newPayload: payload,
+    txMetadata
+  });
+  return {
+    payload,
+    txMetadata
+  };
+};
+
+const getScaleApi = (connector, hexMetadata, token, hasCheckMetadataHash, signedExtensions, registryTypes) => {
+  const decoded = decodeMetadata(hexMetadata);
+  assert(decoded.metadata, `Missing Metadata V14+ for chain ${connector.chainId}`);
+  const {
+    metadata
+  } = decoded;
+  const lookup = getLookupFn$1(metadata);
+  const builder = getDynamicBuilder(lookup);
+  const chain = {
+    connector: getSapiConnector(connector),
+    hexMetadata,
+    token,
+    hasCheckMetadataHash,
+    signedExtensions,
+    registryTypes,
+    metadata,
+    lookup,
+    builder
+  };
+  const chainInfo = getChainInfo(chain);
+  const {
+    specName,
+    specVersion,
+    base58Prefix
+  } = chainInfo;
+  return {
+    id: `${connector.chainId}::${specName}::${specVersion}`,
+    chainId: connector.chainId,
+    specName,
+    specVersion,
+    hasCheckMetadataHash,
+    base58Prefix,
+    token: chain.token,
+    getConstant: (pallet, constant) => getConstantValue(chain, pallet, constant),
+    getStorage: (pallet, entry, keys, at) => getStorageValue(chain, pallet, entry, keys, at),
+    getDecodedCall: (pallet, method, args) => getDecodedCall(pallet, method, args),
+    getDecodedCallFromPayload: payload => getDecodedCallFromPayload(chain, payload),
+    getExtrinsicPayload: (pallet, method, args, config) => getSignerPayloadJSON(chain, pallet, method, args, config, chainInfo),
+    getFeeEstimate: payload => getFeeEstimate(chain, payload, chainInfo),
+    getRuntimeCallValue: (apiName, method, args) => getRuntimeCallResult(chain, apiName, method, args),
+    getTypeRegistry: payload => getTypeRegistry(chain, payload),
+    submit: (payload, signature) => chain.connector.submit(payload, signature),
+    getCallDocs: (pallet, method) => getCallDocs(chain, pallet, method),
+    getDryRunCall: (from, decodedCall) => getDryRunCall(chain, from, decodedCall),
+    isApiAvailable: (name, method) => isApiAvailable(chain, name, method)
+  };
+};
+
+export { getScaleApi };

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@talismn/sapi",
+  "version": "0.0.0-pr1876-20250414012202",
+  "author": "Talisman",
+  "homepage": "https://talisman.xyz",
+  "license": "GPL-3.0-or-later",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "directory": "packages/sapi",
+    "type": "git",
+    "url": "https://github.com/talismansociety/talisman.git"
+  },
+  "main": "dist/talismn-sapi.cjs.js",
+  "module": "dist/talismn-sapi.esm.js",
+  "files": [
+    "/dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@polkadot-api/merkleize-metadata": "1.1.14",
+    "@polkadot-api/metadata-builders": "0.10.2",
+    "@polkadot-api/substrate-bindings": "0.11.1",
+    "@polkadot-api/utils": "0.1.2",
+    "@polkadot/types": "15.8.1",
+    "@polkadot/types-codec": "15.8.1",
+    "@polkadot/util": "13.4.3",
+    "anylogger": "^1.0.11",
+    "polkadot-api": "1.7.6",
+    "@talismn/scale": "0.0.0-pr1876-20250414012202"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "eslint": "^8.57.1",
+    "jest": "^29.7",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.6.3",
+    "@talismn/eslint-config": "0.0.3",
+    "@talismn/tsconfig": "0.0.2"
+  },
+  "eslintConfig": {
+    "root": true,
+    "extends": [
+      "@talismn/eslint-config/base"
+    ]
+  },
+  "scripts": {
+    "test": "jest",
+    "lint": "eslint src --max-warnings 0",
+    "clean": "rm -rf dist .turbo node_modules"
+  }
+}