feat(oracle-runtime): add ixo-transaction wallet-signing plugin

packages/ixo-transaction/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "ixo-transaction",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Qiforge plugin and typed schemas for validating IXO transactions and dispatching Portal wallet signing",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ixoworld/qiforge.git"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./qiforge": {
+      "types": "./dist/qiforge/index.d.ts",
+      "import": "./dist/qiforge/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "validate": "tsx scripts/validate-ixo-tx.ts",
+    "render": "tsx scripts/render-signing-action.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ixo/common": "workspace:*",
+    "zod": "^4.4.3",
+    "zod3": "npm:zod@^3.25.0"
+  },
+  "peerDependencies": {
+    "@ixo/impactxclient-sdk": "^2.3.1",
+    "@ixo/oracle-runtime": "^1.0.32",
+    "@ixo/oracles-client-sdk": "^1.2.2"
+  },
+  "peerDependenciesMeta": {
+    "@ixo/impactxclient-sdk": {
+      "optional": true
+    },
+    "@ixo/oracles-client-sdk": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@ixo/impactxclient-sdk": "^2.4.1",
+    "@ixo/oracle-runtime": "workspace:*",
+    "@ixo/oracles-client-sdk": "workspace:*",
+    "@ixo/typescript-config": "workspace:*",
+    "@ixo/vitest-config": "workspace:*",
+    "@types/node": "^22.10.5",
+    "tsx": "^4.20.3",
+    "typescript": "^5.7.3",
+    "vitest": "^3.2.4"
+  }
+}

packages/ixo-transaction/scripts/render-signing-action.ts

@@ -0,0 +1,3 @@
+import { runCli } from '../src/cli.js';
+
+runCli('render');

packages/ixo-transaction/scripts/validate-ixo-tx.ts

@@ -0,0 +1,3 @@
+import { runCli } from '../src/cli.js';
+
+runCli('validate');

packages/ixo-transaction/src/action.ts

@@ -0,0 +1,187 @@
+import { z } from 'zod';
+
+import {
+  ITrxMsgSchema,
+  NetworkSchema,
+  RiskConfirmationSchema,
+  TestnetReceiptSchema,
+  TransactionDraftSchema,
+  type ITrxMsg,
+} from './schemas.js';
+import { validateTransactionDraft } from './validate.js';
+
+export const SIGN_TRANSACTION_ACTION_NAME = 'sign_transaction';
+
+export const SIGN_TRANSACTION_ACTION_DESCRIPTION =
+  'Sign a validated IXO transaction in the user Portal wallet.';
+
+export const IntentActionMetadataSchema = z
+  .object({
+    source: z.enum([
+      'slash-command',
+      'natural-language',
+      'type-url',
+      'explicit-route',
+    ]),
+    module: z.string().min(1),
+    action: z.string().min(1),
+    messageName: z.string().min(1),
+    typeUrl: z.string().regex(/^\/[A-Za-z0-9.]+\.Msg[A-Za-z0-9]+$/),
+    confidence: z.number().min(0).max(1),
+    ambiguities: z.array(z.string()),
+  })
+  .strict();
+
+export const SignTransactionActionArgsSchema = z
+  .object({
+    action: z.literal(SIGN_TRANSACTION_ACTION_NAME),
+    network: NetworkSchema,
+    messages: z.array(ITrxMsgSchema).min(1),
+    memo: z.string().optional(),
+    intent: IntentActionMetadataSchema,
+    risks: z.array(z.string()),
+    riskLevel: z.enum(['low', 'medium', 'high', 'critical']),
+    requiresConfirmation: z.boolean(),
+    riskConfirmation: RiskConfirmationSchema.optional(),
+    testnetReceipt: TestnetReceiptSchema.optional(),
+    overrideMainnet: z.boolean().optional(),
+    overrideReason: z.string().min(1).optional(),
+  })
+  .strict();
+
+export type SignTransactionActionArgs = z.infer<
+  typeof SignTransactionActionArgsSchema
+>;
+
+export const SignTransactionActionResultSchema = z
+  .object({
+    success: z.boolean(),
+    transactionHash: z.string().min(1).optional(),
+    code: z.number().int().optional(),
+    height: z.union([z.string(), z.number().int()]).optional(),
+    error: z.string().optional(),
+    result: z.unknown().optional(),
+  })
+  .strict();
+
+export type SignTransactionActionResult = z.infer<
+  typeof SignTransactionActionResultSchema
+>;
+
+export type WalletSignTransactionFn = (
+  messages: readonly ITrxMsg[],
+  memo?: string,
+) => Promise<unknown>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function readStringField(
+  value: Record<string, unknown>,
+  fields: readonly string[],
+): string | undefined {
+  for (const field of fields) {
+    const candidate = value[field];
+    if (typeof candidate === 'string' && candidate.length > 0) {
+      return candidate;
+    }
+  }
+  return undefined;
+}
+
+function readNumberField(
+  value: Record<string, unknown>,
+  fields: readonly string[],
+): number | undefined {
+  for (const field of fields) {
+    const candidate = value[field];
+    if (typeof candidate === 'number' && Number.isInteger(candidate)) {
+      return candidate;
+    }
+  }
+  return undefined;
+}
+
+export function buildSignTransactionActionArgs(
+  input: unknown,
+): SignTransactionActionArgs {
+  const draft = TransactionDraftSchema.parse(input);
+  const validated = validateTransactionDraft(draft, {
+    requireRiskConfirmation: true,
+  });
+
+  return SignTransactionActionArgsSchema.parse({
+    action: SIGN_TRANSACTION_ACTION_NAME,
+    network: validated.network,
+    messages: [validated.message],
+    memo: draft.memo,
+    intent: validated.intent,
+    risks: validated.risks,
+    riskLevel: validated.riskLevel,
+    requiresConfirmation: validated.requiresConfirmation,
+    riskConfirmation: draft.riskConfirmation,
+    testnetReceipt: draft.testnetReceipt,
+    overrideMainnet: draft.overrideMainnet,
+    overrideReason: draft.overrideReason,
+  });
+}
+
+export function normalizeWalletSignResult(
+  result: unknown,
+): SignTransactionActionResult {
+  if (result === undefined || result === null) {
+    return SignTransactionActionResultSchema.parse({
+      success: false,
+      error: 'Portal wallet did not return a transaction result',
+    });
+  }
+
+  if (!isRecord(result)) {
+    return SignTransactionActionResultSchema.parse({
+      success: true,
+      result,
+    });
+  }
+
+  const transactionHash = readStringField(result, [
+    'transactionHash',
+    'txHash',
+    'hash',
+  ]);
+  const code = readNumberField(result, ['code']);
+  const height =
+    readStringField(result, ['height']) ?? readNumberField(result, ['height']);
+  const explicitSuccess =
+    typeof result.success === 'boolean' ? result.success : undefined;
+  const success = explicitSuccess ?? (code === undefined || code === 0);
+  const error = success
+    ? undefined
+    : (readStringField(result, ['error', 'rawLog', 'log']) ??
+      `Transaction failed with code ${code ?? 'unknown'}`);
+
+  return SignTransactionActionResultSchema.parse({
+    success,
+    transactionHash,
+    code,
+    height,
+    error,
+    result,
+  });
+}
+
+export async function signIxoTransactionWithWallet(
+  input: unknown,
+  transactSignX: WalletSignTransactionFn,
+): Promise<SignTransactionActionResult> {
+  try {
+    const args = SignTransactionActionArgsSchema.parse(input);
+    const result = await transactSignX(args.messages, args.memo);
+    return normalizeWalletSignResult(result);
+  } catch (error) {
+    return SignTransactionActionResultSchema.parse({
+      success: false,
+      error: error instanceof Error ? error.message : 'Wallet signing failed',
+    });
+  }
+}