@monolythium/core-sdk 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @monolythium/core-sdk
 
-Official TypeScript SDK for [Monolythium v4.0](https://monolythium.com) (LythiumDAG-BFT).
+Official TypeScript SDK for [Monolythium v4.1](https://monolythium.com) (LythiumDAG-BFT).
 
 ## Install
 
@@ -29,34 +29,49 @@ const markets = await client.lythClobMarkets(25);
 console.log(decoded.status, holders.holders.length, txs.transactions.length, markets.markets.length);
 ```
 
-The client wraps every JSON-RPC method served by a Monolythium node — the
-EVM-compatible `eth_*` / `net_*` / `web3_*` surface and the chain-native
-`lyth_*` and `debug_*` namespaces, including live explorer helpers such as
+The client wraps the Monolythium node JSON-RPC surface: current chain-native
+`lyth_*` methods, passive compatibility `eth_*` / `net_*` / `web3_*` reads, and
+server-gated debug methods. The no-EVM v4.1 path should use native helpers such
+as
 `lyth_decodeTx`, `lyth_gapRecords`, `lyth_dagParents`, `lyth_richList`,
 `lyth_txFeed`, `lyth_addressProfile`, `lyth_addressFlow`, `lyth_search`,
 `lyth_chainStats`, `lyth_clobMarkets`, `lyth_clobTrades`, `lyth_clobOhlc`,
-`lyth_clobOrderBook`, and `lyth_addressActivityKind`. Wire types are generated
-from the Rust SDK via `ts-rs` where possible, with SDK-local convenience types
-for newer explorer envelopes.
+`lyth_clobOrderBook`, `lyth_nativeReceipt`, and `lyth_addressActivityKind`.
+Wire types are generated from the Rust SDK via `ts-rs` where possible, with
+SDK-local convenience types for newer explorer envelopes.
 
 Quantities surface as `bigint` to preserve full precision. Use
 `parseQuantity` only when you know the value fits in `Number.MAX_SAFE_INTEGER`.
 
+### MRC accounts
+
+```ts
+const mrcAccount = await client.lythMrcAccount("monos1effvdw0d05a35j69wwxplhmctpcclx382n60yf", 10);
+console.log(mrcAccount.smartAccount?.controller, mrcAccount.policySpends.length);
+```
+
 ### Node API client
 
 The SDK also exports `ApiClient` for the node's REST-shaped `/api/v1` surface.
 Pass the JSON-RPC endpoint; the client derives `/api/v1` automatically.
 
 ```ts
-import { ApiClient } from "@monolythium/core-sdk";
+import { ApiClient, addressToTypedBech32 } from "@monolythium/core-sdk";
 
 const api = new ApiClient("https://rpc.testnet.monolythium.com");
 
 const latest = await api.block("latest");
 const txs = await api.blockTransactions("latest", 0, 25);
-const activity = await api.addressActivity("0x123456789abcdef0112233445566778899aabbcc");
-
-console.log(latest.data.block.blockHash, txs.data.totalTransactions, activity.data.entries.length);
+const nativeReceipt = await api.transactionNativeReceipt("0x...");
+const account = addressToTypedBech32("user", "0x123456789abcdef0112233445566778899aabbcc");
+const activity = await api.addressActivity(account);
+
+console.log(
+  latest.data.block.blockHash,
+  txs.data.totalTransactions,
+  nativeReceipt.data.eventCount,
+  activity.data.entries.length,
+);
 ```
 
 ### Chain registry
@@ -86,14 +101,72 @@ the first one that answers with the expected chain id.
 
 ### Address helpers
 
-User-facing surfaces should display Monolythium addresses as `mono1...`
-bech32m, while JSON-RPC still uses 20-byte `0x...` hex.
+Public v4.1 SDK, JSON-RPC, REST, wallet, and explorer surfaces use ADR-0038
+typed bech32m addresses. User accounts use `mono1...`; smart-account MRC
+lookups use `monos1...`; RISC-V contracts use `monoc1...`. Raw `0x` strings
+remain only for low-level byte conversion helpers and compatibility adapters.
 
 ```ts
 import { addressToBech32, bech32ToAddress } from "@monolythium/core-sdk";
 
 const display = addressToBech32("0x123456789abcdef0112233445566778899aabbcc");
-const wire = bech32ToAddress(display);
+const hex = bech32ToAddress(display);
+```
+
+V4.1 typed address helpers also encode role-specific HRPs such as `monoc` for
+RISC-V contracts:
+
+```ts
+import { addressToTypedBech32, typedBech32ToAddress } from "@monolythium/core-sdk";
+
+const contract = addressToTypedBech32("contract", "0x2222222222222222222222222222222222222222");
+const decoded = typedBech32ToAddress(contract, "contract");
+```
+
+### MRV / RISC-V helpers
+
+The package includes the first v4.1 MRV SDK slice: artifact metadata
+validation, MRV v1 transaction extension descriptors, typed contract address
+helpers, and native deploy/call request builders with lythoshi and
+execution-unit fields.
+
+```ts
+import {
+  MRV_FORMAT_VERSION,
+  MRV_PROFILE_MONO_RV32IM_V1,
+  buildMrvCallPlan,
+  buildMrvDeployPlan,
+  deriveMrvContractAddress,
+  mrvAddressToBech32,
+  mrvCodeHashHex,
+  validateMrvArtifactMetadata,
+} from "@monolythium/core-sdk";
+
+const code = new Uint8Array([0x13, 0x00, 0x00, 0x00]);
+const metadata = {
+  formatVersion: MRV_FORMAT_VERSION,
+  profile: MRV_PROFILE_MONO_RV32IM_V1,
+  codeHash: mrvCodeHashHex(code),
+  codeBytes: 4n,
+  debugBytes: 0n,
+  abi: { symbols: [{ name: "transfer", kind: "function", inputs: [], outputs: [] }] },
+  imports: [{ module: "mono", name: "emit_event", id: 0x0302 }],
+  memory: { initialPages: 1, maxPages: 4, stackBytes: 16384 },
+  storageNamespace: { name: "contract_state", version: 1 },
+  build: { toolchain: "mono-riscv", sourceDigest: `0x${"00".repeat(32)}`, profile: "release" },
+};
+
+const validated = validateMrvArtifactMetadata(metadata, code);
+const deployer = mrvAddressToBech32("user", new Uint8Array(20).fill(0x11));
+const deployAddress = deriveMrvContractAddress(deployer, 7n, validated.codeHash);
+const deploy = buildMrvDeployPlan("0x13000000", {
+  from: deployer,
+  nonce: 7n,
+  artifactHash: validated.codeHash,
+  executionUnitLimit: 1_000_000n,
+});
+const call = buildMrvCallPlan(deployAddress, [0x01, 0x02]);
+console.log(validated.syscalls, deploy.extension, deploy.expectedContractAddress, call.request);
 ```
 
 ### Spending-policy helpers
@@ -102,6 +175,8 @@ Fresh sub-account policy claims must use `claimPolicyByAddress` or
 `setPolicyClaim`, both of which bind the policy to a sub-account ML-DSA-65
 signature. Prefer `claimPolicyByAddress` after the pubkey is registered in
 pubkey-registry; it avoids carrying the 1952-byte pubkey in calldata.
+`policyArgs.subAccount` and `policyArgs.principal` must be typed `mono1...`
+bech32m account addresses.
 
 ```ts
 import {
@@ -122,16 +197,31 @@ primary ML-DSA-65 pubkey once, so contracts can look it up by address.
 
 ```ts
 import {
+  addressToTypedBech32,
   encodeRegisterPubkeyCalldata,
   encodeLookupPubkeyCalldata,
   decodeLookupPubkeyReturn,
 } from "@monolythium/core-sdk";
 
+const account = addressToTypedBech32("user", "0x123456789abcdef0112233445566778899aabbcc");
 const calldata = encodeRegisterPubkeyCalldata(mlDsa65Pubkey);
-const lookup = encodeLookupPubkeyCalldata("0x123456789abcdef0112233445566778899aabbcc");
+const lookup = encodeLookupPubkeyCalldata(account);
 const decoded = decodeLookupPubkeyReturn(returnData);
 ```
 
+### Bridge route readiness
+
+Bridge helpers assess explicit route disclosures and fail closed. The SDK can
+select a route for an intent, but it cannot produce a live quote or submit
+payload until `mono-core` exposes those API/runtime primitives.
+
+```ts
+import { bridgeQuoteSubmitReadiness } from "@monolythium/core-sdk";
+
+const readiness = bridgeQuoteSubmitReadiness(intent, routeDisclosures);
+console.log(readiness.routeSelectionReady, readiness.quoteReady, readiness.blockedReasons);
+```
+
 ### PQM-1 + ML-DSA-65 helpers
 
 Wallets and faucets can derive deterministic ML-DSA-65 backends directly in
@@ -150,26 +240,27 @@ const backend = pqm1MnemonicToMlDsa65Backend(mnemonic);
 const signature = backend.sign(new Uint8Array([1, 2, 3]));
 ```
 
-### ethers.js v6 compat
+### Legacy ethers.js v6 compat
 
-The package also ships an ethers v6 compat shim — a `MonolythiumProvider`
-and `MonolythiumSigner` that drop in wherever ethers' `Provider` and
-`Signer` are expected. `ethers` is a peer dependency.
+The package still ships an ethers v6 compat shim for legacy migration tooling:
+a `MonolythiumProvider` and `MonolythiumSigner` that drop in wherever ethers'
+`Provider` and `Signer` are expected. It is not the v4.1 no-EVM deployment path;
+new app work should use the MRV/RISC-V builders and `lyth_*` read surfaces.
+`ethers` is a peer dependency for this compatibility path.
 
 ```ts
-import { Wallet, ContractFactory } from "ethers";
+import { Wallet } from "ethers";
 import {
   MonolythiumProvider,
   MonolythiumSigner,
-} from "@monolythium/core-sdk";
+} from "@monolythium/core-sdk/ethers";
 
 const provider = new MonolythiumProvider("https://rpc.testnet.monolythium.com");
 const wallet = new Wallet(process.env.PRIVATE_KEY!);
 const signer = MonolythiumSigner.fromEthersWallet(wallet, provider);
 
-const factory = new ContractFactory(abi, bytecode, signer);
-const contract = await factory.deploy();
-await contract.waitForDeployment();
+// Legacy-only adapter setup. Do not use this path for new v4.1 MRV deployments.
+console.log(await signer.getAddress());
 ```
 
 For non-secp256k1 signing sources (OS keychain, hardware wallet, future

package/dist/crypto/index.cjs

@@ -1,6 +1,7 @@
 'use strict';
 
 var mlDsa_js = require('@noble/post-quantum/ml-dsa.js');
+var blake3_js = require('@noble/hashes/blake3.js');
 var sha3_js = require('@noble/hashes/sha3.js');
 var bip39 = require('@scure/bip39');
 var english_js = require('@scure/bip39/wordlists/english.js');
@@ -145,8 +146,7 @@ function encodeTransactionForHash(fields, tag) {
     n.input,
     new Uint8Array(4),
     // access_list length
-    new Uint8Array(4)
-    // extensions length
+    encodeExtensionsForHash(n.extensions)
   );
 }
 function bincodeSignedTransaction(fields, signature, publicKey) {
@@ -163,7 +163,8 @@ function bincodeSignedTransaction(fields, signature, publicKey) {
   w.rawBytes(uint256Le(n.value, "value"));
   w.bytes(n.input);
   w.u64(0n);
-  w.u64(0n);
+  w.u64(BigInt(n.extensions.length));
+  for (const ext of n.extensions) bincodeTypedExtensionInto(w, ext);
   bincodeMlDsa65OpaqueInto(w, sig);
   bincodeMlDsa65OpaqueInto(w, pk);
   return w.toBytes();
@@ -177,7 +178,8 @@ function normalizeTxFields(fields) {
     gasLimit: parseBigint(fields.gasLimit, "gasLimit"),
     to: normalizeTo(fields.to),
     value: parseBigint(fields.value, "value"),
-    input: normalizeBytes(fields.input ?? new Uint8Array(0), "input")
+    input: normalizeBytes(fields.input ?? new Uint8Array(0), "input"),
+    extensions: normalizeExtensions(fields.extensions)
   };
 }
 function normalizeTo(value) {
@@ -189,6 +191,30 @@ function normalizeBytes(value, label) {
   if (typeof value === "string") return hexToBytes(value, label);
   return value instanceof Uint8Array ? value : Uint8Array.from(value);
 }
+function normalizeExtensions(value) {
+  if (value === void 0) return [];
+  return value.map((ext, index) => {
+    if (!Number.isInteger(ext.kind) || ext.kind < 0 || ext.kind > 255) {
+      throw new Error(`extensions[${index}].kind out of u8 range`);
+    }
+    const body = normalizeBytes("bodyHex" in ext ? ext.bodyHex : ext.body, `extensions[${index}].body`);
+    if (body.length > 4294967295) {
+      throw new Error(`extensions[${index}].body exceeds u32 length`);
+    }
+    return { kind: ext.kind, body };
+  });
+}
+function encodeExtensionsForHash(extensions) {
+  const chunks = [bigintToBeBytes(BigInt(extensions.length), 4, "extensions.length")];
+  for (const ext of extensions) {
+    chunks.push(
+      Uint8Array.of(ext.kind),
+      bigintToBeBytes(BigInt(ext.body.length), 4, "extension.body.length"),
+      ext.body
+    );
+  }
+  return concatBytes(...chunks);
+}
 function uint256Le(value, label) {
   if (value < 0n || value >= 1n << 256n) throw new Error(`${label} out of u256 range`);
   const out = new Uint8Array(32);
@@ -204,6 +230,10 @@ function bincodeMlDsa65OpaqueInto(w, raw) {
   w.u16(STANDARD_ALGO_NUMBER_ML_DSA_65);
   w.bytes(raw);
 }
+function bincodeTypedExtensionInto(w, ext) {
+  w.u8(ext.kind);
+  w.bytes(ext.body);
+}
 
 // src/crypto/ml-dsa.ts
 var ML_DSA_65_SEED_LEN = 32;
@@ -212,6 +242,8 @@ var ML_DSA_65_PUBLIC_KEY_LEN = 1952;
 var ML_DSA_65_SIGNATURE_LEN = 3309;
 var STANDARD_ALGO_NUMBER_ML_DSA_65 = 1001;
 var ENUM_VARIANT_INDEX_ML_DSA_65 = 5;
+var ADDRESS_DERIVATION_DOMAIN = "MONO_ADDRESS_BLAKE3_20_V1";
+var ADDRESS_DERIVATION_DOMAIN_BYTES = new TextEncoder().encode(ADDRESS_DERIVATION_DOMAIN);
 var MlDsa65Backend = class _MlDsa65Backend {
   #secretKey;
   #publicKey;
@@ -219,7 +251,7 @@ var MlDsa65Backend = class _MlDsa65Backend {
   constructor(secretKey, publicKey) {
     this.#secretKey = expectBytes(secretKey, ML_DSA_65_SIGNING_KEY_LEN, "ML-DSA-65 secret key").slice();
     this.#publicKey = expectBytes(publicKey, ML_DSA_65_PUBLIC_KEY_LEN, "ML-DSA-65 public key").slice();
-    this.#addressBytes = sha3_js.keccak_256(this.#publicKey).slice(12);
+    this.#addressBytes = mlDsa65AddressBytes(this.#publicKey);
   }
   static fromSeed(seed) {
     const kp = mlDsa_js.ml_dsa65.keygen(expectBytes(seed, ML_DSA_65_SEED_LEN, "ML-DSA-65 seed"));
@@ -268,7 +300,15 @@ var MlDsa65Backend = class _MlDsa65Backend {
   }
 };
 function mlDsa65AddressFromPublicKey(publicKey) {
-  return bytesToHex(sha3_js.keccak_256(expectBytes(publicKey, ML_DSA_65_PUBLIC_KEY_LEN, "ML-DSA-65 public key")).slice(12));
+  return bytesToHex(mlDsa65AddressBytes(publicKey));
+}
+function mlDsa65AddressBytes(publicKey) {
+  const bytes = expectBytes(publicKey, ML_DSA_65_PUBLIC_KEY_LEN, "ML-DSA-65 public key");
+  return blake3_js.blake3(concatBytes(
+    ADDRESS_DERIVATION_DOMAIN_BYTES,
+    bigintToBeBytes(BigInt(STANDARD_ALGO_NUMBER_ML_DSA_65), 2, "ML-DSA-65 algo id"),
+    bytes
+  )).slice(0, 20);
 }
 function encodeMlDsa65Opaque(raw) {
   const bytes = raw instanceof Uint8Array ? raw : Uint8Array.from(raw);
@@ -387,6 +427,8 @@ var MempoolClass = {
   PrivacyOp: 2,
   CLOBOp: 3,
   AgentOp: 4,
+  FoundationOp: 5,
+  /** @deprecated Use FoundationOp. */
   GovernanceOp: 5,
   RWAOp: 6
 };
@@ -490,7 +532,6 @@ async function fetchEncryptionKey(client) {
   };
 }
 async function buildEncryptedSubmission(args) {
-  const signed = args.backend.signEvmTx(args.tx);
   const input = normalizeInput(args.tx.input);
   const to = normalizeTo2(args.tx.to);
   const nonceAad = {
@@ -498,10 +539,14 @@ async function buildEncryptedSubmission(args) {
     nonce: parseBigint(args.tx.nonce, "nonce"),
     chainId: parseBigint(args.tx.chainId, "chainId"),
     class: args.class ?? (to !== null && input.length === 0 ? MempoolClass.Transfer : MempoolClass.ContractCall),
-    maxFeePerGas: u128Saturate(parseBigint(args.tx.maxFeePerGas, "maxFeePerGas")),
-    maxPriorityFeePerGas: u128Saturate(parseBigint(args.tx.maxPriorityFeePerGas, "maxPriorityFeePerGas")),
+    maxFeePerGas: u128Checked(parseBigint(args.tx.maxFeePerGas, "maxFeePerGas"), "maxFeePerGas"),
+    maxPriorityFeePerGas: u128Checked(
+      parseBigint(args.tx.maxPriorityFeePerGas, "maxPriorityFeePerGas"),
+      "maxPriorityFeePerGas"
+    ),
     gasLimit: parseBigint(args.tx.gasLimit, "gasLimit")
   };
+  const signed = args.backend.signEvmTx(args.tx);
   const decryptionHint = { epoch: args.encryptionKey.epoch, scheme: 0 };
   const built = await buildEncryptedEnvelope({
     signedInnerTxBincode: signed.wireBytes,
@@ -515,16 +560,19 @@ async function buildEncryptedSubmission(args) {
   return {
     envelopeWireHex: built.wireHex,
     innerSighashHex: `0x${[...signed.sighash].map((b) => b.toString(16).padStart(2, "0")).join("")}`,
+    innerTxHashHex: bytesToHex(signed.txHash),
     innerWireBytes: signed.wireBytes.length
   };
 }
 async function submitEncryptedEnvelope(client, envelopeWireHex) {
   return client.call("lyth_submitEncrypted", [envelopeWireHex]);
 }
-function u128Saturate(value) {
+function u128Checked(value, field) {
   const cap = (1n << 128n) - 1n;
-  if (value < 0n) return 0n;
-  return value > cap ? cap : value;
+  if (value < 0n || value > cap) {
+    throw new Error(`${field} must fit in u128 for encrypted nonce AAD`);
+  }
+  return value;
 }
 function normalizeTo2(value) {
   if (value === null) return null;
@@ -539,6 +587,7 @@ function normalizeInput(value) {
   return value instanceof Uint8Array ? value : Uint8Array.from(value);
 }
 
+exports.ADDRESS_DERIVATION_DOMAIN = ADDRESS_DERIVATION_DOMAIN;
 exports.BincodeWriter = BincodeWriter;
 exports.DKG_AEAD_TAG_LEN = DKG_AEAD_TAG_LEN;
 exports.DKG_NONCE_LEN = DKG_NONCE_LEN;
@@ -580,6 +629,7 @@ exports.expectBytes = expectBytes;
 exports.fetchEncryptionKey = fetchEncryptionKey;
 exports.generatePqm1Mnemonic = generatePqm1Mnemonic;
 exports.hexToBytes = hexToBytes;
+exports.mlDsa65AddressBytes = mlDsa65AddressBytes;
 exports.mlDsa65AddressFromPublicKey = mlDsa65AddressFromPublicKey;
 exports.outerSigDigest = outerSigDigest;
 exports.parsePqm1Payload = parsePqm1Payload;