codama-renderers-dart 0.3.1 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codama-renderers-dart",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Codama renderer for generating Dart code targeting the solana_kit SDK",
   "exports": {
     "node": {
@@ -30,6 +30,11 @@
     "code-generator"
   ],
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openbudgetfun/solana_kit.git",
+    "directory": "packages/codama-renderers-dart"
+  },
   "dependencies": {
     "@codama/errors": "^1.4.4",
     "@codama/nodes": "^1.4.4",
@@ -38,7 +43,8 @@
   },
   "devDependencies": {
     "@codama/nodes-from-anchor": "^1.3.9",
-    "@codama/renderers-js": "^2.0.2"
+    "@codama/renderers-js": "^2.0.2",
+    "@vitest/coverage-v8": "3.2.4"
   },
   "engines": {
     "node": ">=18"
@@ -50,6 +56,7 @@
     "build": "pnpm exec rimraf dist && pnpm exec tsup && pnpm exec tsc -p tsconfig.declarations.json",
     "lint": "eslint --ext .ts src",
     "test": "pnpm exec vitest run",
+    "test:coverage": "pnpm exec vitest run --coverage.enabled --coverage.reporter=lcov",
     "test:watch": "pnpm exec vitest",
     "typecheck": "pnpm exec tsc --noEmit"
   }

package/readme.md

@@ -1,5 +1,9 @@
 # codama-renderers-dart
 
+[![pub package](https://img.shields.io/pub/v/codama-renderers-dart.svg)](https://pub.dev/packages/codama-renderers-dart)
+[![CI](https://github.com/openbudgetfun/solana_kit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/openbudgetfun/solana_kit/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/openbudgetfun/solana_kit/branch/main/graph/badge.svg?flag=codama-renderers-dart)](https://codecov.io/gh/openbudgetfun/solana_kit?flag=codama-renderers-dart)
+
 A [Codama](https://github.com/codama-idl/codama) renderer that generates Dart code targeting the [solana_kit](https://github.com/openbudgetfun/solana_kit) SDK.
 
 Given a Codama IDL (Interface Description Language) describing a Solana program, this renderer produces a complete Dart package with typed account classes, instruction builders, codec functions, error definitions, PDA helpers, and barrel exports.
@@ -9,6 +13,10 @@ Given a Codama IDL (Interface Description Language) describing a Solana program,
 ```bash
 pnpm add codama-renderers-dart
 # or
+
+[![pub package](https://img.shields.io/pub/v/codama-renderers-dart.svg)](https://pub.dev/packages/codama-renderers-dart)
+[![CI](https://github.com/openbudgetfun/solana_kit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/openbudgetfun/solana_kit/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/openbudgetfun/solana_kit/branch/main/graph/badge.svg?flag=codama-renderers-dart)](https://codecov.io/gh/openbudgetfun/solana_kit?flag=codama-renderers-dart)
 npm install codama-renderers-dart
 ```
 
@@ -277,18 +285,38 @@ Key source files:
 
 ```bash
 # Install dependencies
+
+[![pub package](https://img.shields.io/pub/v/codama-renderers-dart.svg)](https://pub.dev/packages/codama-renderers-dart)
+[![CI](https://github.com/openbudgetfun/solana_kit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/openbudgetfun/solana_kit/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/openbudgetfun/solana_kit/branch/main/graph/badge.svg?flag=codama-renderers-dart)](https://codecov.io/gh/openbudgetfun/solana_kit?flag=codama-renderers-dart)
 pnpm install
 
 # Type check
+
+[![pub package](https://img.shields.io/pub/v/codama-renderers-dart.svg)](https://pub.dev/packages/codama-renderers-dart)
+[![CI](https://github.com/openbudgetfun/solana_kit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/openbudgetfun/solana_kit/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/openbudgetfun/solana_kit/branch/main/graph/badge.svg?flag=codama-renderers-dart)](https://codecov.io/gh/openbudgetfun/solana_kit?flag=codama-renderers-dart)
 npx tsc --noEmit
 
 # Run tests
+
+[![pub package](https://img.shields.io/pub/v/codama-renderers-dart.svg)](https://pub.dev/packages/codama-renderers-dart)
+[![CI](https://github.com/openbudgetfun/solana_kit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/openbudgetfun/solana_kit/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/openbudgetfun/solana_kit/branch/main/graph/badge.svg?flag=codama-renderers-dart)](https://codecov.io/gh/openbudgetfun/solana_kit?flag=codama-renderers-dart)
 pnpm test
 
 # Watch mode
+
+[![pub package](https://img.shields.io/pub/v/codama-renderers-dart.svg)](https://pub.dev/packages/codama-renderers-dart)
+[![CI](https://github.com/openbudgetfun/solana_kit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/openbudgetfun/solana_kit/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/openbudgetfun/solana_kit/branch/main/graph/badge.svg?flag=codama-renderers-dart)](https://codecov.io/gh/openbudgetfun/solana_kit?flag=codama-renderers-dart)
 pnpm test:watch
 
 # Build
+
+[![pub package](https://img.shields.io/pub/v/codama-renderers-dart.svg)](https://pub.dev/packages/codama-renderers-dart)
+[![CI](https://github.com/openbudgetfun/solana_kit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/openbudgetfun/solana_kit/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/openbudgetfun/solana_kit/branch/main/graph/badge.svg?flag=codama-renderers-dart)](https://codecov.io/gh/openbudgetfun/solana_kit?flag=codama-renderers-dart)
 pnpm build
 ```
 

package/src/fragments/instructionPage.ts

@@ -1,4 +1,4 @@
-import type {
+import {
   InstructionAccountNode,
   InstructionArgumentNode,
   InstructionNode,
@@ -16,6 +16,7 @@ import {
 import type { RenderScope } from "../utils/options.js";
 import { camelCase, pascalCase } from "../utils/nameTransformers.js";
 import { getDiscriminatorConstantsFragment } from "./discriminatorConstants.js";
+import { WELL_KNOWN_ADDRESSES } from "../utils/wellKnownAddresses.js";
 
 /**
  * Generate a full Dart file for an instruction.
@@ -53,15 +54,28 @@ export function getInstructionPageFragment(
     .join("\n");
 
   const dataCtorParams = allArgManifests
-    .map(({ arg }) => {
+    .map(({ arg, manifest }) => {
       const fieldName = camelCase(arg.name as string);
       if (isDiscriminatorArg(arg, node)) {
-        return `    this.${fieldName} = ${getDiscriminatorDefault(arg, node)},`;
+        return isConstDefaultValue(arg.defaultValue)
+          ? `    this.${fieldName} = ${getDiscriminatorDefault(arg, node)},`
+          : `    ${manifest.type.content}? ${fieldName},`;
       }
       return `    required this.${fieldName},`;
     })
     .join("\n");
 
+  const dataCtorInitializers = allArgManifests
+    .map(({ arg }) => {
+      const fieldName = camelCase(arg.name as string);
+      if (isDiscriminatorArg(arg, node) && !isConstDefaultValue(arg.defaultValue)) {
+        return `      ${fieldName} = ${fieldName} ?? ${getDiscriminatorDefault(arg, node)}`;
+      }
+      return null;
+    })
+    .filter((value): value is string => value !== null)
+    .join(",\n");
+
   // Encoder/decoder for instruction data
   const encFields = allArgManifests
     .map(({ arg, manifest }) => {
@@ -91,10 +105,17 @@ export function getInstructionPageFragment(
     })
     .join("\n");
 
+  const dataCtorKeyword = dataCtorInitializers ? "" : "const ";
   const dataEncoderName = `get${typeName}InstructionDataEncoder`;
   const dataDecoderName = `get${typeName}InstructionDataDecoder`;
   const dataCodecName = `get${typeName}InstructionDataCodec`;
 
+  // Determine whether any arg or account name collides with 'programAddress'
+  const argNames = new Set(args.map((a) => camelCase(a.name as string)));
+  const accountNames = new Set(accounts.map((a) => camelCase(a.name as string)));
+  const hasProgramAddressCollision = argNames.has('programAddress') || accountNames.has('programAddress');
+  const instrProgramParam = hasProgramAddressCollision ? 'instructionProgramAddress' : 'programAddress';
+
   // Build the instruction builder function
   const accountParams = accounts
     .map((acc) => {
@@ -112,11 +133,14 @@ export function getInstructionPageFragment(
     .map((arg) => {
       const manifest = argManifestMap.get(arg)!;
       const fieldName = camelCase(arg.name as string);
+      const typeStr = manifest.type.content;
       const hasDefault = arg.defaultValue != null;
       if (hasDefault) {
-        return `  ${manifest.type.content}? ${fieldName},`;
+        // Don't add `?` if the type is already nullable.
+        const nullableType = typeStr.endsWith("?") ? typeStr : `${typeStr}?`;
+        return `  ${nullableType} ${fieldName},`;
       }
-      return `  required ${manifest.type.content} ${fieldName},`;
+      return `  required ${typeStr} ${fieldName},`;
     })
     .join("\n");
 
@@ -140,6 +164,7 @@ export function getInstructionPageFragment(
       if (isDiscriminatorArg(arg, node)) {
         return ""; // Use default
       }
+      // Use 'arg_<name>' prefix to reference builder params without shadowing.
       return `      ${fieldName}: ${fieldName}${arg.defaultValue != null ? ` ?? ${getDefaultValue(arg)}` : ""},`;
     })
     .filter(Boolean)
@@ -174,9 +199,9 @@ ${use("AccountRole", "solanaInstructions")}`,
   parts.push(fragment`
 @immutable
 class ${fragmentFromString(dataClassName)} {
-  const ${fragmentFromString(dataClassName)}({
+  ${fragmentFromString(dataCtorKeyword)}${fragmentFromString(dataClassName)}({
 ${fragmentFromString(dataCtorParams)}
-  });
+  })${fragmentFromString(dataCtorInitializers ? ` :\n${dataCtorInitializers}` : "")};
 
 ${fragmentFromString(dataFieldDecls)}
 }`);
@@ -217,20 +242,20 @@ Codec<${fragmentFromString(dataClassName)}, ${fragmentFromString(dataClassName)}
   parts.push(fragment`
 /// Creates a [${fragmentFromString(typeName)}] instruction.
 Instruction ${fragmentFromString(instrFnName)}({
-  required Address programAddress,
+  required Address ${fragmentFromString(instrProgramParam)},
 ${fragmentFromString(accountParams)}
 ${fragmentFromString(argParams)}
 }) {
-  final data = ${fragmentFromString(dataClassName)}(
+  final instructionData = ${fragmentFromString(dataClassName)}(
 ${fragmentFromString(dataConstruction)}
   );
 
   return Instruction(
-    programAddress: programAddress,
+    programAddress: ${fragmentFromString(instrProgramParam)},
     accounts: [
 ${fragmentFromString(accountMetas)}
     ],
-    data: ${fragmentFromString(dataEncoderName)}().encode(data),
+    data: ${fragmentFromString(dataEncoderName)}().encode(instructionData),
   );
 }`);
 
@@ -282,10 +307,28 @@ function getDiscriminatorDefault(
     if (arg.defaultValue.kind === "numberValueNode") {
       return String(arg.defaultValue.number);
     }
+    if (arg.defaultValue.kind === "bytesValueNode") {
+      const data = arg.defaultValue.data as string;
+      const bytes = data.match(/.{1,2}/g)?.map((b) => parseInt(b, 16)) ?? [];
+      return `Uint8List.fromList([${bytes.join(", ")}])`;
+    }
   }
   return "0";
 }
 
+function isConstDefaultValue(defaultValue: InstructionArgumentNode["defaultValue"]): boolean {
+  if (!defaultValue) return false;
+  switch (defaultValue.kind) {
+    case "numberValueNode":
+    case "booleanValueNode":
+    case "stringValueNode":
+    case "noneValueNode":
+      return true;
+    default:
+      return false;
+  }
+}
+
 function getDefaultValue(arg: InstructionArgumentNode): string {
   if (!arg.defaultValue) return "null";
   const dv = arg.defaultValue;
@@ -296,10 +339,20 @@ function getDefaultValue(arg: InstructionArgumentNode): string {
       return String(dv.boolean);
     case "stringValueNode":
       return `'${dv.string}'`;
-    case "publicKeyValueNode":
+    case "publicKeyValueNode": {
+      const wellKnownName = WELL_KNOWN_ADDRESSES.get(dv.publicKey);
+      if (wellKnownName) {
+        use(wellKnownName, "solanaAddresses");
+        return wellKnownName;
+      }
       return `Address('${dv.publicKey}')`;
+    }
     case "noneValueNode":
       return "null";
+    case "bytesValueNode": {
+      const bytes = dv.data.match(/.{1,2}/g)?.map((b) => parseInt(b, 16)) ?? [];
+      return `Uint8List.fromList([${bytes.join(", ")}])`;
+    }
     default:
       return "null";
   }

package/src/fragments/pdaPage.ts

@@ -10,6 +10,7 @@ import {
 } from "../utils/fragment.js";
 import type { RenderScope } from "../utils/options.js";
 import { camelCase, pascalCase } from "../utils/nameTransformers.js";
+import { WELL_KNOWN_ADDRESSES } from "../utils/wellKnownAddresses.js";
 
 /**
  * Generate a full Dart file for a PDA.
@@ -23,6 +24,11 @@ export function getPdaPageFragment(
   const seedsClassName = `${pascalCase(name)}Seeds`;
 
   const seeds = node.seeds ?? [];
+  const hasByteSeeds = seeds.some(
+    (seed) =>
+      seed.kind === "constantPdaSeedNode" &&
+      seed.value.kind === "bytesValueNode",
+  );
 
   // Separate variable seeds from constant seeds
   const variableSeeds = seeds.filter(
@@ -59,9 +65,17 @@ export function getPdaPageFragment(
       } else if (seed.value.kind === "stringValueNode") {
         seedValues.push(`    '${seed.value.string}',`);
       } else if (seed.value.kind === "publicKeyValueNode") {
-        seedValues.push(
-          `    getAddressEncoder().encode(Address('${seed.value.publicKey}')),`,
-        );
+        const wellKnownSeedName = WELL_KNOWN_ADDRESSES.get(seed.value.publicKey);
+        if (wellKnownSeedName) {
+          use(wellKnownSeedName, "solanaAddresses");
+          seedValues.push(
+            `    getAddressEncoder().encode(${wellKnownSeedName}),`,
+          );
+        } else {
+          seedValues.push(
+            `    getAddressEncoder().encode(Address('${seed.value.publicKey}')),`,
+          );
+        }
       } else if (seed.value.kind === "numberValueNode") {
         const manifest = visit(seed.type, scope.typeManifestVisitor);
         seedValues.push(`    ${manifest.encoder.content}.encode(${seed.value.number}),`);
@@ -75,15 +89,27 @@ export function getPdaPageFragment(
   }
 
   // Program address parameter
+  const wellKnownProgramName = node.programId
+    ? WELL_KNOWN_ADDRESSES.get(node.programId)
+    : undefined;
+  if (wellKnownProgramName) {
+    use(wellKnownProgramName, "solanaAddresses");
+  }
   const programIdParam = node.programId
-    ? `Address programAddress = const Address('${node.programId}')`
+    ? wellKnownProgramName
+      ? `Address programAddress = ${wellKnownProgramName}`
+      : `Address programAddress = const Address('${node.programId}')`
     : "required Address programAddress";
 
+  const typedDataImport = hasByteSeeds
+    ? use("Uint8List", "dartTypedData")
+    : fragmentFromString("");
+
   const parts: Fragment[] = [
     fragment`// Auto-generated. Do not edit.
 // ignore_for_file: type=lint
 
-${use("Uint8List", "dartTypedData")}
+${typedDataImport}
 ${use("immutable", "meta")}
 ${use("Address", "solanaAddresses")}
 ${use("getAddressEncoder", "solanaAddresses")}
@@ -110,13 +136,13 @@ Future<(Address, int)> ${fragmentFromString(findFnName)}({
 ${fragmentFromString(seedsParam)}
   ${fragmentFromString(programIdParam)},
 }) async {
-  final seeds = <Object>[
+  final seedValues = <Object>[
 ${fragmentFromString(seedValues.join("\n"))}
   ];
 
   return getProgramDerivedAddress(
     programAddress: programAddress,
-    seeds: seeds,
+    seeds: seedValues,
   );
 }`);
 

package/src/fragments/programPage.ts

@@ -10,6 +10,7 @@ import {
 } from "../utils/fragment.js";
 import type { RenderScope } from "../utils/options.js";
 import { camelCase, pascalCase } from "../utils/nameTransformers.js";
+import { WELL_KNOWN_ADDRESSES } from "../utils/wellKnownAddresses.js";
 
 /**
  * Generate a full Dart file for a program.
@@ -21,15 +22,36 @@ export function getProgramPageFragment(
   const name = node.name as string;
   const addressConstName = scope.nameApi.programAddressConstant(name);
 
-  const parts: Fragment[] = [
-    fragment`// Auto-generated. Do not edit.
+  const wellKnownName = WELL_KNOWN_ADDRESSES.get(node.publicKey);
+
+  // For well-known addresses, export and alias the canonical constant from
+  // solana_kit_addresses instead of hardcoding the address string.
+  // When the generated name matches the canonical name, a simple export suffices.
+  // When they differ, we also need a local const alias.
+  // For unknown addresses, fall back to the original Address('...') pattern.
+  const addressDeclaration: Fragment = wellKnownName
+    ? addressConstName === wellKnownName
+      ? fragment`// Auto-generated. Do not edit.
+// ignore_for_file: type=lint
+
+/// The address of the ${fragmentFromString(pascalCase(name))} program.
+export 'package:solana_kit_addresses/solana_kit_addresses.dart' show ${fragmentFromString(wellKnownName)};`
+      : fragment`${use(wellKnownName, "solanaAddresses")}
+
+// Auto-generated. Do not edit.
+// ignore_for_file: type=lint
+
+/// The address of the ${fragmentFromString(pascalCase(name))} program.
+const ${fragmentFromString(addressConstName)} = ${fragmentFromString(wellKnownName)};`
+    : fragment`// Auto-generated. Do not edit.
 // ignore_for_file: type=lint
 
 ${use("Address", "solanaAddresses")}
 
 /// The address of the ${fragmentFromString(pascalCase(name))} program.
-const ${fragmentFromString(addressConstName)} = Address('${fragmentFromString(node.publicKey)}');`,
-  ];
+const ${fragmentFromString(addressConstName)} = Address('${fragmentFromString(node.publicKey)}');`;
+
+  const parts: Fragment[] = [addressDeclaration];
 
   // Account identifier enum
   const accounts = node.accounts ?? [];
@@ -60,4 +82,4 @@ ${fragmentFromString(instrVariants)}
   }
 
   return mergeFragments(parts, (cs) => cs.join("\n"));
-}
+}

package/src/fragments/typePage.ts

@@ -125,6 +125,8 @@ function getDataEnumPageFragment(
   const variantClasses: string[] = [];
   const encoderVariants: string[] = [];
   const decoderVariants: string[] = [];
+  const encodeCases: string[] = [];
+  const decodeCases: string[] = [];
   // Collect all field type manifests from variants so we can merge their imports
   const allVariantManifests: { encoder: Fragment; decoder: Fragment; type: Fragment }[] = [];
 
@@ -154,8 +156,10 @@ function getDataEnumPageFragment(
         `(${i}, getStructEncoder(<(String, Encoder<Object?>)>[]))`,
       );
       decoderVariants.push(
-        `(${i}, getStructDecoder(<(String, Decoder<Object?>)>[]).map((_) => const ${variantClassName}()))`,
+        `(${i}, transformDecoder<Map<String, Object?>, Map<String, Object?>>(getStructDecoder(<(String, Decoder<Object?>)>[]), (Map<String, Object?> map, Uint8List bytes, int offset) => <String, Object?>{}))`,
       );
+      encodeCases.push(`${variantClassName}() => <String, Object?>{'__kind': ${i}},`);
+      decodeCases.push(`case ${i}: return const ${variantClassName}();`);
     } else if (variant.kind === "enumStructVariantTypeNode") {
       const resolvedStruct = resolveNestedTypeNode(variant.struct);
       const fields = resolvedStruct.fields;
@@ -178,23 +182,28 @@ function getDataEnumPageFragment(
       const ctorParams = fields
         .map((f: StructFieldTypeNode) => `    required this.${camelCase(f.name as string)},`)
         .join("\n");
-
-      const eqChecks = fields
-        .map((f: StructFieldTypeNode) => `${camelCase(f.name as string)} == other.${camelCase(f.name as string)}`)
-        .join(" &&\n          ");
-
-      const hashFields = fields
-        .map((f: StructFieldTypeNode) => camelCase(f.name as string))
-        .join(", ");
+      const ctorSignature =
+        fields.length === 0
+          ? `  const ${variantClassName}();`
+          : `  const ${variantClassName}({\n${ctorParams}\n  });`;
+
+      const eqChecks =
+        fields.length === 0
+          ? "true"
+          : fields
+              .map((f: StructFieldTypeNode) => `${camelCase(f.name as string)} == other.${camelCase(f.name as string)}`)
+              .join(" &&\n          ");
+
+      const hashExpression = getHashExpression(
+        fields.map((f: StructFieldTypeNode) => camelCase(f.name as string)),
+      );
 
       const toStringFields = fields
         .map((f: StructFieldTypeNode) => `${camelCase(f.name as string)}: $${camelCase(f.name as string)}`)
         .join(", ");
 
       variantClasses.push(`final class ${variantClassName} extends ${typeName} {
-  const ${variantClassName}({
-${ctorParams}
-  });
+${ctorSignature}
 
 ${fieldDecls}
 
@@ -205,7 +214,7 @@ ${fieldDecls}
           ${eqChecks};
 
   @override
-  int get hashCode => Object.hash(${hashFields});
+  int get hashCode => ${hashExpression};
 
   @override
   String toString() => '${typeName}.${variantClassName}(${toStringFields})';
@@ -242,11 +251,23 @@ ${fieldDecls}
         .join(", ");
 
       encoderVariants.push(
-        `(${i}, transformEncoder(getStructEncoder([${encFields}]), (${variantClassName} value) => <String, Object?>{${toMapFields}}))`,
+        `(${i}, getStructEncoder([${encFields}]))`,
       );
       decoderVariants.push(
-        `(${i}, transformDecoder(getStructDecoder([${decFields}]), (Map<String, Object?> map, Uint8List bytes, int offset) => ${variantClassName}(${fromMapFields})))`,
+        `(${i}, transformDecoder<Map<String, Object?>, Map<String, Object?>>(getStructDecoder([${decFields}]), (Map<String, Object?> map, Uint8List bytes, int offset) => map))`,
       );
+      const structPattern =
+        fields.length === 0
+          ? ''
+          : fields
+              .map((f: StructFieldTypeNode) => `${camelCase(f.name as string)}: final ${camelCase(f.name as string)}`)
+              .join(', ');
+      const structMapEntries =
+        fields.length === 0
+          ? ''
+          : `, ${fields.map((f: StructFieldTypeNode)=>`'${f.name as string}': ${camelCase(f.name as string)}`).join(', ')}`;
+      encodeCases.push(`${variantClassName}(${structPattern}) => <String, Object?>{'__kind': ${i}${structMapEntries}},`);
+      decodeCases.push(`case ${i}: return ${variantClassName}(${fromMapFields.replace(/\n/g, ' ').replace(/,$/, '')});`);
     } else if (variant.kind === "enumTupleVariantTypeNode") {
       const resolvedTuple = resolveNestedTypeNode(variant.tuple);
       const items = resolvedTuple.items;
@@ -270,11 +291,13 @@ ${fieldDecls}
   String toString() => '${typeName}.${variantClassName}(\$value)';
 }`);
         encoderVariants.push(
-          `(${i}, transformEncoder(${manifest.encoder.content}, (${variantClassName} value) => value.value))`,
+          `(${i}, transformEncoder<${manifest.type.content}, Map<String, Object?>>(${manifest.encoder.content}, (Map<String, Object?> map) => map['value']! as ${manifest.type.content}))`,
         );
         decoderVariants.push(
-          `(${i}, transformDecoder(${manifest.decoder.content}, (${manifest.type.content} value, Uint8List bytes, int offset) => ${variantClassName}(value)))`,
+          `(${i}, transformDecoder<${manifest.type.content}, Map<String, Object?>>(${manifest.decoder.content}, (${manifest.type.content} value, Uint8List bytes, int offset) => <String, Object?>{'value': value}))`,
         );
+        encodeCases.push(`${variantClassName}(value: final value) => <String, Object?>{'__kind': ${i}, 'value': value},`);
+        decodeCases.push(`case ${i}: return ${variantClassName}(map['value']! as ${manifest.type.content});`);
       }
     }
   }
@@ -290,7 +313,6 @@ ${fieldDecls}
 // ignore_for_file: type=lint
 
 ${use("Uint8List", "dartTypedData")}
-${use("immutable", "meta")}
 ${use("Encoder", "solanaCodecsCore")}
 ${use("Decoder", "solanaCodecsCore")}
 ${use("Codec", "solanaCodecsCore")}
@@ -311,15 +333,28 @@ sealed class ${fragmentFromString(typeName)} {
 ${fragmentFromString(variantClasses.join("\n\n"))}
 
 Encoder<${fragmentFromString(typeName)}> ${fragmentFromString(encoderName)}() {
-  return getDiscriminatedUnionEncoder([
-    ${fragmentFromString(encoderVariants.join(",\n    "))},
-  ], size: get${fragmentFromString(sizeCodecName)}Encoder());
+  return transformEncoder<Map<String, Object?>, ${fragmentFromString(typeName)}>(
+    getDiscriminatedUnionEncoder([
+      ${fragmentFromString(encoderVariants.join(",\n      "))},
+    ], size: get${fragmentFromString(sizeCodecName)}Encoder()),
+    (${fragmentFromString(typeName)} value) => switch (value) {
+      ${fragmentFromString(encodeCases.join("\n      "))}
+    },
+  );
 }
 
 Decoder<${fragmentFromString(typeName)}> ${fragmentFromString(decoderName)}() {
-  return getDiscriminatedUnionDecoder([
-    ${fragmentFromString(decoderVariants.join(",\n    "))},
-  ], size: get${fragmentFromString(sizeCodecName)}Decoder());
+  return transformDecoder<Map<String, Object?>, ${fragmentFromString(typeName)}>(
+    getDiscriminatedUnionDecoder([
+      ${fragmentFromString(decoderVariants.join(",\n      "))},
+    ], size: get${fragmentFromString(sizeCodecName)}Decoder()),
+    (Map<String, Object?> map, Uint8List bytes, int offset) {
+      switch (map['__kind']) {
+        ${fragmentFromString(decodeCases.join("\n        "))}
+      }
+      throw StateError('Unsupported ${typeName} discriminator: \${map['__kind']}');
+    },
+  );
 }
 
 Codec<${fragmentFromString(typeName)}, ${fragmentFromString(typeName)}> ${fragmentFromString(codecName)}() {
@@ -365,6 +400,10 @@ function getStructPageFragment(
   const ctorParams = fields
     .map((f: StructFieldTypeNode) => `    required this.${camelCase(f.name as string)},`)
     .join("\n");
+  const ctorSignature =
+    fields.length === 0
+      ? `  const ${typeName}();`
+      : `  const ${typeName}({\n${ctorParams}\n  });`;
 
   const eqChecks =
     fields.length === 0
@@ -376,9 +415,12 @@ function getStructPageFragment(
           )
           .join(" &&\n          ");
 
-  const hashFields = fields
-    .map((f: StructFieldTypeNode) => camelCase(f.name as string))
-    .join(", ");
+  const hashFields =
+    fields.length === 0
+      ? "runtimeType"
+      : fields
+          .map((f: StructFieldTypeNode) => camelCase(f.name as string))
+          .join(", ");
 
   const toStringFields = fields
     .map(
@@ -436,9 +478,7 @@ ${use("getStructDecoder", "solanaCodecsDataStructures")}
 
 @immutable
 class ${fragmentFromString(typeName)} {
-  const ${fragmentFromString(typeName)}({
-${fragmentFromString(ctorParams)}
-  });
+${fragmentFromString(ctorSignature)}
 
 ${fragmentFromString(fieldDecls)}
 
@@ -450,7 +490,7 @@ ${fragmentFromString(fieldDecls)}
           ${fragmentFromString(eqChecks)};
 
   @override
-  int get hashCode => Object.hash(${fragmentFromString(hashFields)});
+  int get hashCode => ${fragmentFromString(getHashExpression(fields.map((f: StructFieldTypeNode) => camelCase(f.name as string))))};
 
   @override
   String toString() => '${fragmentFromString(typeName)}(${fragmentFromString(toStringFields)})';
@@ -534,6 +574,12 @@ Codec<${fragmentFromString(typeName)}, ${fragmentFromString(typeName)}> ${fragme
 }`;
 }
 
+function getHashExpression(fields: string[]): string {
+  if (fields.length === 0) return "runtimeType.hashCode";
+  if (fields.length === 1) return `${fields[0]}.hashCode`;
+  return `Object.hash(${fields.join(", ")})`;
+}
+
 function getNumberCodecName(format: string): string {
   switch (format) {
     case "u8": return "U8";

package/src/utils/index.ts

@@ -5,3 +5,4 @@ export * from "./importMap.js";
 export * from "./nameTransformers.js";
 export * from "./options.js";
 export * from "./typeManifest.js";
+export * from "./wellKnownAddresses.js";

package/src/utils/wellKnownAddresses.ts

@@ -0,0 +1,64 @@
+/**
+ * Maps well-known Solana public keys to their canonical Dart constant names
+ * in `package:solana_kit_addresses`. When the renderer encounters a known
+ * address, it emits a re-export from that package instead of hardcoding the
+ * address string.
+ *
+ * The keys are the base-58 public key strings as they appear in IDL/Codama nodes.
+ * The values are the Dart constant names exported by `solana_kit_addresses`.
+ */
+export const WELL_KNOWN_ADDRESSES: ReadonlyMap<string, string> = new Map([
+  // Agave / Solana native programs
+  ['11111111111111111111111111111111', 'systemProgramAddress'],
+  ['AddressLookupTab1e1111111111111111111111111', 'addressLookupTableProgramAddress'],
+  ['BPFLoader2111111111111111111111111111111111', 'bpfLoaderProgramAddress'],
+  ['BPFLoader1111111111111111111111111111111111', 'bpfLoaderDeprecatedProgramAddress'],
+  ['BPFLoaderUpgradeab1e11111111111111111111111', 'bpfLoaderUpgradeableProgramAddress'],
+  ['ComputeBudget111111111111111111111111111111', 'computeBudgetProgramAddress'],
+  ['Config1111111111111111111111111111111111111', 'configProgramAddress'],
+  ['Ed25519SigVerify111111111111111111111111111', 'ed25519ProgramAddress'],
+  ['Feature111111111111111111111111111111111111', 'featureProgramAddress'],
+  ['1nc1nerator11111111111111111111111111111111', 'incineratorAddress'],
+  ['LoaderV411111111111111111111111111111111111', 'loaderV4ProgramAddress'],
+  ['NativeLoader1111111111111111111111111111', 'nativeLoaderProgramAddress'],
+  ['KeccakSecp256k11111111111111111111111111111', 'secp256k1ProgramAddress'],
+  ['Secp256r1SigVerify1111111111111111111111111', 'secp256r1ProgramAddress'],
+  ['Stake11111111111111111111111111111111111111', 'stakeProgramAddress'],
+  ['StakeConfig1111111111111111111111111111', 'stakeConfigAddress'],
+  ['Vote111111111111111111111111111111111111111', 'voteProgramAddress'],
+  ['ZkTokenProof1111111111111111111111111111111', 'zkTokenProofProgramAddress'],
+  ['ZkE1Gama1Proof11111111111111111111111111111', 'zkElgamalProofProgramAddress'],
+
+  // Sysvars
+  ['SysvarC1ock11111111111111111111111111111111', 'sysvarClockAddress'],
+  ['Rent11111111111111111111111111111111111111', 'sysvarRentAddress'],
+  ['11111111111111111111111111111111111111111111', 'sysvarRecentBlockhashesAddress'], // note: 44 chars
+  ['SysvarFees1111111111111111111111111111111111', 'sysvarFeesAddress'],
+  ['Sysvar1nstruct1ons11111111111111111111111111', 'sysvarInstructionsAddress'],
+  ['SysvarEpochSchedu1e111111111111111111111111', 'sysvarEpochScheduleAddress'],
+  ['SysvarRewards111111111111111111111111111111', 'sysvarRewardsAddress'],
+  ['SysvarStakeHistory1111111111111111111111111', 'sysvarStakeHistoryAddress'],
+  ['SysvarS1otHashes111111111111111111111111111', 'sysvarSlotHashesAddress'],
+  ['SysvarS1otHistory11111111111111111111111111', 'sysvarSlotHistoryAddress'],
+  ['Sysvar1111111111111111111111111111111111111', 'sysvarOwnerAddress'],
+
+  // SPL programs
+  ['TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA', 'tokenProgramAddress'],
+  ['TokenzQdBNb4qyze1S1U9AHB8MGXmNK1REkTPT5Z3Y', 'token2022ProgramAddress'],
+  ['ATokenGPvbdGVxr1b2hvZbsiqW5xWH25ef7s3c8BnQKu', 'associatedTokenProgramAddress'],
+  ['Memo1UhkJRfRhVq1sR7Y7Nto1s3J2mXTT3L6Wk4K2m6', 'memoProgramAddress'],
+  ['MemoSq4gqABXKKYWVqKkV3m3kb1cTR7F2UMy9r6kFNK', 'memoLegacyProgramAddress'],
+
+  // Metaplex programs
+  ['metaqbxxU9qX8rZXkmUJ7haCrXXz2W1PSUq1Rn3E1od', 'tokenMetadataProgramAddress'],
+  ['BGUMAp9V1mQ2KV8t34L5u3gZsXYZaYDBdKkc1xYk1qA1', 'mplBubblegumProgramAddress'],
+  ['auth9SigNpDKz4s8cHr3MFBPS1phbRKLSCN3aBe9sS', 'authRulesProgramAddress'],
+  ['CoREENxT6tW1Ho6BW6W5Z4N41ci5Xz2mmrR2kErmM5TR', 'metaplexCoreProgramAddress'],
+  ['cmtMqR4bPM9sEV3bPnJQq5s2EnYw4N5vQ8hWhEd1xzS', 'splAccountCompressionProgramAddress'],
+  ['noopb9skMVngR5Qi4sczwFr1jU4V4F7nm8xzFQK9C', 'noopProgramAddress'],
+
+  // Well-known mints
+  ['So11111111111111111111111111111111111111112', 'wrappedSolAddress'],
+  ['EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', 'usdcAddress'],
+  ['Es9vMFrzaCERm6YKXx6bqKr1Rmd9b5v3J8rM5e4rfF4', 'usdtAddress'],
+]);

package/src/visitors/getRenderMapVisitor.ts

@@ -89,7 +89,10 @@ export function getRenderMapVisitor(
             ...node.additionalPrograms.map((p) => visit(p, self)),
           ];
 
-          return mergeRenderMaps(programMaps);
+          const mergedProgramMap = mergeRenderMaps(programMaps);
+          const categoryMaps = getSharedCategoryIndexMaps(mergedProgramMap);
+
+          return mergeRenderMaps([mergedProgramMap, ...categoryMaps]);
         },
 
         visitProgram(node: ProgramNode, { self }) {
@@ -151,76 +154,15 @@ export function getRenderMapVisitor(
             maps.push(errorMap);
           }
 
-          // Barrel exports
+          // Root barrel
           const categories: string[] = [];
+          if (accountFiles.length > 0) categories.push("accounts");
+          if (instructionFiles.length > 0) categories.push("instructions");
+          if (typeFiles.length > 0) categories.push("types");
+          if (pdaFiles.length > 0) categories.push("pdas");
+          if (errorFiles.length > 0) categories.push("errors");
+          if (programFiles.length > 0) categories.push("programs");
 
-          if (accountFiles.length > 0) {
-            categories.push("accounts");
-            let indexMap = createRenderMap<Fragment>();
-            indexMap = addToRenderMap(
-              indexMap,
-              "accounts/accounts.dart",
-              getIndexPageFragment(accountFiles),
-            );
-            maps.push(indexMap);
-          }
-
-          if (instructionFiles.length > 0) {
-            categories.push("instructions");
-            let indexMap = createRenderMap<Fragment>();
-            indexMap = addToRenderMap(
-              indexMap,
-              "instructions/instructions.dart",
-              getIndexPageFragment(instructionFiles),
-            );
-            maps.push(indexMap);
-          }
-
-          if (typeFiles.length > 0) {
-            categories.push("types");
-            let indexMap = createRenderMap<Fragment>();
-            indexMap = addToRenderMap(
-              indexMap,
-              "types/types.dart",
-              getIndexPageFragment(typeFiles),
-            );
-            maps.push(indexMap);
-          }
-
-          if (pdaFiles.length > 0) {
-            categories.push("pdas");
-            let indexMap = createRenderMap<Fragment>();
-            indexMap = addToRenderMap(
-              indexMap,
-              "pdas/pdas.dart",
-              getIndexPageFragment(pdaFiles),
-            );
-            maps.push(indexMap);
-          }
-
-          if (errorFiles.length > 0) {
-            categories.push("errors");
-            let indexMap = createRenderMap<Fragment>();
-            indexMap = addToRenderMap(
-              indexMap,
-              "errors/errors.dart",
-              getIndexPageFragment(errorFiles),
-            );
-            maps.push(indexMap);
-          }
-
-          if (programFiles.length > 0) {
-            categories.push("programs");
-            let indexMap = createRenderMap<Fragment>();
-            indexMap = addToRenderMap(
-              indexMap,
-              "programs/programs.dart",
-              getIndexPageFragment(programFiles),
-            );
-            maps.push(indexMap);
-          }
-
-          // Root barrel
           if (categories.length > 0) {
             let rootMap = createRenderMap<Fragment>();
             rootMap = addToRenderMap(
@@ -270,3 +212,46 @@ export function getRenderMapVisitor(
     (v) => recordLinkablesOnFirstVisitVisitor(v, linkables),
   );
 }
+
+function getSharedCategoryIndexMaps(
+  renderMap: RenderMap<Fragment>,
+): RenderMap<Fragment>[] {
+  const categories = new Map<string, Set<string>>();
+  const categoryIndexNames: Record<string, string> = {
+    accounts: "accounts.dart",
+    instructions: "instructions.dart",
+    types: "types.dart",
+    pdas: "pdas.dart",
+    errors: "errors.dart",
+    programs: "programs.dart",
+  };
+
+  for (const renderPath of renderMap.keys()) {
+    const match = renderPath.match(
+      /^(accounts|instructions|types|pdas|errors|programs)\/([^/]+\.dart)$/,
+    );
+    if (!match) continue;
+
+    const [, category, fileName] = match;
+    if (fileName === categoryIndexNames[category]) continue;
+
+    if (!categories.has(category)) {
+      categories.set(category, new Set());
+    }
+    categories.get(category)!.add(fileName);
+  }
+
+  const maps: RenderMap<Fragment>[] = [];
+  for (const [category, files] of categories.entries()) {
+    const sortedFiles = [...files].sort();
+    let map = createRenderMap<Fragment>();
+    map = addToRenderMap(
+      map,
+      `${category}/${categoryIndexNames[category]}`,
+      getIndexPageFragment(sortedFiles),
+    );
+    maps.push(map);
+  }
+
+  return maps;
+}

package/src/visitors/getTypeManifestVisitor.ts

@@ -417,6 +417,7 @@ export function getTypeManifestVisitor(input: {
 
     visitOptionType(node: OptionTypeNode, { self }) {
       const itemManifest = visit(node.item, self);
+      const itemTypeStr = itemManifest.type.content;
       const resolvedPrefix = resolveNestedTypeNode(node.prefix);
       const prefixExpr = resolvedPrefix.format !== "u8"
         ? `, prefix: ${getNumberCodecExpression(resolvedPrefix.format, "Encoder")}`
@@ -424,17 +425,20 @@ export function getTypeManifestVisitor(input: {
       const prefixDecoderExpr = resolvedPrefix.format !== "u8"
         ? `, prefix: ${getNumberCodecExpression(resolvedPrefix.format, "Decoder")}`
         : "";
+      const noneValueExpr = node.fixed
+        ? ", noneValue: const ZeroesNoneValue()"
+        : "";
 
       return {
         type: fragment`${itemManifest.type}?`,
         encoder: fragment`${use(
           "getNullableEncoder",
           "solanaCodecsDataStructures",
-        )}(${itemManifest.encoder}${fragmentFromString(prefixExpr)})`,
+        )}<${fragmentFromString(itemTypeStr)}>(${itemManifest.encoder}${fragmentFromString(prefixExpr)}${fragmentFromString(noneValueExpr)})`,
         decoder: fragment`${use(
           "getNullableDecoder",
           "solanaCodecsDataStructures",
-        )}(${itemManifest.decoder}${fragmentFromString(prefixDecoderExpr)})`,
+        )}<${fragmentFromString(itemTypeStr)}>(${itemManifest.decoder}${fragmentFromString(prefixDecoderExpr)}${fragmentFromString(noneValueExpr)})`,
         value: emptyTypeManifest().value,
         isEnum: false,
       };
@@ -445,17 +449,18 @@ export function getTypeManifestVisitor(input: {
       { self },
     ) {
       const itemManifest = visit(node.item, self);
+      const itemTypeStr = itemManifest.type.content;
 
       return {
         type: fragment`${itemManifest.type}?`,
         encoder: fragment`${use(
           "getNullableEncoder",
           "solanaCodecsDataStructures",
-        )}(${itemManifest.encoder}, hasPrefix: false)`,
+        )}<${fragmentFromString(itemTypeStr)}>(${itemManifest.encoder}, hasPrefix: false)`,
         decoder: fragment`${use(
           "getNullableDecoder",
           "solanaCodecsDataStructures",
-        )}(${itemManifest.decoder}, hasPrefix: false)`,
+        )}<${fragmentFromString(itemTypeStr)}>(${itemManifest.decoder}, hasPrefix: false)`,
         value: emptyTypeManifest().value,
         isEnum: false,
       };
@@ -466,17 +471,18 @@ export function getTypeManifestVisitor(input: {
       { self },
     ) {
       const itemManifest = visit(node.item, self);
+      const itemTypeStr = itemManifest.type.content;
 
       return {
         type: fragment`${itemManifest.type}?`,
         encoder: fragment`${use(
           "getNullableEncoder",
           "solanaCodecsDataStructures",
-        )}(${itemManifest.encoder}, hasPrefix: false, noneValue: const ZeroesNoneValue())`,
+        )}<${fragmentFromString(itemTypeStr)}>(${itemManifest.encoder}, hasPrefix: false, noneValue: const ZeroesNoneValue())`,
         decoder: fragment`${use(
           "getNullableDecoder",
           "solanaCodecsDataStructures",
-        )}(${itemManifest.decoder}, hasPrefix: false, noneValue: const ZeroesNoneValue())`,
+        )}<${fragmentFromString(itemTypeStr)}>(${itemManifest.decoder}, hasPrefix: false, noneValue: const ZeroesNoneValue())`,
         value: emptyTypeManifest().value,
         isEnum: false,
       };
@@ -502,7 +508,26 @@ export function getTypeManifestVisitor(input: {
 
     visitSizePrefixType(node: SizePrefixTypeNode, { self }) {
       const innerManifest = visit(node.type, self);
-      const prefixManifest = visit(node.prefix, self);
+
+      // The Dart addEncoderSizePrefix / addDecoderSizePrefix APIs require
+      // Encoder<num> / Decoder<num> for the prefix. BigInt-width number types
+      // (u64, u128, i64, i128) return Encoder<BigInt> which is incompatible.
+      // When the IDL specifies such a prefix, substitute u32 which is wide
+      // enough for any realistic size prefix and satisfies the num constraint.
+      const bigIntFormats = new Set(["u64", "u128", "i64", "i128"]);
+      let prefixManifest;
+      if (
+        node.prefix.kind === "numberTypeNode" &&
+        bigIntFormats.has((node.prefix as any).format)
+      ) {
+        // Use u32 encoder/decoder instead of the oversized type.
+        prefixManifest = {
+          encoder: fragment`${use("getU32Encoder", "solanaCodecsNumbers")}()`,
+          decoder: fragment`${use("getU32Decoder", "solanaCodecsNumbers")}()`,
+        };
+      } else {
+        prefixManifest = visit(node.prefix, self);
+      }
 
       return {
         type: innerManifest.type,
@@ -521,7 +546,7 @@ export function getTypeManifestVisitor(input: {
 
     visitHiddenPrefixType(node: HiddenPrefixTypeNode, { self }) {
       const innerManifest = visit(node.type, self);
-      const prefixes = node.prefix.map((p) => visit(p, self));
+      const prefixes = node.prefix.map((p) => getHiddenAffixManifest(p, self));
       const prefixEncoders = prefixes
         .map((p) => p.encoder.content)
         .join(", ");
@@ -556,7 +581,7 @@ export function getTypeManifestVisitor(input: {
 
     visitHiddenSuffixType(node: HiddenSuffixTypeNode, { self }) {
       const innerManifest = visit(node.type, self);
-      const suffixes = node.suffix.map((s) => visit(s, self));
+      const suffixes = node.suffix.map((s) => getHiddenAffixManifest(s, self));
       const suffixEncoders = suffixes
         .map((s) => s.encoder.content)
         .join(", ");
@@ -792,3 +817,55 @@ function getSetSizeExpression(node: SetTypeNode): string {
       return "";
   }
 }
+
+type HiddenAffixManifest = {
+  encoder: Fragment;
+  decoder: Fragment;
+};
+
+function getHiddenAffixManifest(
+  node: any,
+  self: Visitor<TypeManifest>,
+): HiddenAffixManifest {
+  if (node?.kind !== "constantValueNode") {
+    const manifest = visit(node, self);
+    return { encoder: manifest.encoder, decoder: manifest.decoder };
+  }
+
+  const constantBytes = getConstantBytesExpression(node);
+  return {
+    encoder: fragment`${use("getConstantEncoder", "solanaCodecsDataStructures")}(${constantBytes})`,
+    decoder: fragment`${use("getConstantDecoder", "solanaCodecsDataStructures")}(${constantBytes})`,
+  };
+}
+
+function getConstantBytesExpression(node: any): Fragment {
+  const valueNode = node.value;
+  const typeNode = node.type;
+
+  if (valueNode?.kind !== "numberValueNode") {
+    throw new Error(
+      `Unsupported hidden affix constant value kind: ${valueNode?.kind}`,
+    );
+  }
+
+  const value = Number(valueNode.number);
+
+  if (typeNode?.kind === "numberTypeNode") {
+    return fragment`${use(`get${getNumberCodecName(typeNode.format)}Encoder`, "solanaCodecsNumbers")}().encode(${value})`;
+  }
+
+  if (typeNode?.kind === "preOffsetTypeNode") {
+    const inner = typeNode.type;
+    if (inner?.kind !== "numberTypeNode") {
+      throw new Error(
+        `Unsupported hidden affix pre-offset inner type kind: ${inner?.kind}`,
+      );
+    }
+    return fragment`${use("padLeftEncoder", "solanaCodecsCore")}(${use(`get${getNumberCodecName(inner.format)}Encoder`, "solanaCodecsNumbers")}(), ${typeNode.offset}).encode(${value})`;
+  }
+
+  throw new Error(
+    `Unsupported hidden affix constant type kind: ${typeNode?.kind}`,
+  );
+}