@subql/common-solana 0.0.0-1

package/src/codegen/index.ts

@@ -0,0 +1,5 @@
+// Copyright 2020-2025 SubQuery Pte Ltd authors & contributors
+// SPDX-License-Identifier: GPL-3.0
+
+export * from './codegen';
+export * from './idl';

package/src/index.ts

@@ -0,0 +1,16 @@
+// Copyright 2020-2025 SubQuery Pte Ltd authors & contributors
+// SPDX-License-Identifier: GPL-3.0
+
+export * from './codegen';
+export * from './project';
+
+import {SolanaNetworkModule} from '@subql/types-solana';
+import * as c from './codegen';
+import * as p from './project';
+
+// This provides a compiled time check to ensure that the correct exports are provided
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _ = {
+  ...p,
+  ...c,
+} satisfies SolanaNetworkModule;

package/src/project/index.ts

@@ -0,0 +1,11 @@
+// Copyright 2020-2025 SubQuery Pte Ltd authors & contributors
+// SPDX-License-Identifier: GPL-3.0
+
+export * from './load';
+export * from './models';
+export * from './types';
+export * from './utils';
+export * from './versioned';
+
+import { parseSolanaProjectManifest } from './load';
+export { parseSolanaProjectManifest as parseProjectManifest };

package/src/project/load.ts

@@ -0,0 +1,10 @@
+// Copyright 2020-2025 SubQuery Pte Ltd authors & contributors
+// SPDX-License-Identifier: GPL-3.0
+
+import { SolanaProjectManifestVersioned, VersionedProjectManifest } from './versioned';
+
+export function parseSolanaProjectManifest(raw: unknown): SolanaProjectManifestVersioned {
+  const projectManifest = new SolanaProjectManifestVersioned(raw as VersionedProjectManifest);
+  projectManifest.validate();
+  return projectManifest;
+}

package/src/project/models.ts

@@ -0,0 +1,213 @@
+// Copyright 2020-2025 SubQuery Pte Ltd authors & contributors
+// SPDX-License-Identifier: GPL-3.0
+
+import {BaseDataSource, BlockFilterImpl, forbidNonWhitelisted} from '@subql/common';
+import {FileReference} from '@subql/types-core';
+import {
+  SolanaHandlerKind,
+  SolanaDatasourceKind,
+  SolanaLogFilter,
+  SubqlCustomHandler,
+  SubqlMapping,
+  SubqlHandler,
+  SubqlRuntimeHandler,
+  SubqlRuntimeDatasource,
+  SubqlCustomDatasource,
+  SubqlBlockHandler,
+  SubqlTransactionHandler,
+  SolanaTransactionFilter,
+  SolanaBlockFilter,
+  SolanaInstructionFilter,
+  SubqlInstructionHandler,
+  SubqlLogHandler,
+  InstructionAccountFilter,
+} from '@subql/types-solana';
+import {plainToClass, Transform, Type} from 'class-transformer';
+import {
+  IsArray,
+  IsEnum,
+  IsOptional,
+  IsString,
+  IsObject,
+  ValidateNested,
+  ValidateIf,
+  IsDefined,
+  IsBoolean,
+} from 'class-validator';
+
+export class BlockFilter extends BlockFilterImpl implements SolanaBlockFilter {}
+
+export class TransactionFilter implements SolanaTransactionFilter {
+  @IsOptional()
+  @IsString()
+  signerAccountKey?: string;
+}
+
+export class InstructionFilter implements SolanaInstructionFilter {
+  @ValidateIf((o) => o.discriminator !== undefined)
+  @IsDefined({message: 'programId is required if discriminator is set'})
+  @IsString()
+  programId?: string;
+
+  @IsOptional()
+  @IsString()
+  discriminator?: string;
+
+  @IsOptional()
+  @IsArray()
+  accounts?: [
+    InstructionAccountFilter,
+    InstructionAccountFilter?,
+    InstructionAccountFilter?,
+    InstructionAccountFilter?,
+    InstructionAccountFilter?,
+    InstructionAccountFilter?,
+    InstructionAccountFilter?,
+    InstructionAccountFilter?,
+    InstructionAccountFilter?,
+    InstructionAccountFilter?,
+    InstructionAccountFilter?,
+    InstructionAccountFilter?,
+    InstructionAccountFilter?,
+    InstructionAccountFilter?,
+    InstructionAccountFilter?,
+    InstructionAccountFilter?
+  ];
+
+  @IsOptional()
+  @IsBoolean()
+  includeFalied?: boolean;
+}
+
+export class LogFilter implements SolanaLogFilter {
+  @IsOptional()
+  @IsString()
+  programId?: string;
+}
+
+export class BlockHandler implements SubqlBlockHandler {
+  @IsObject()
+  @IsOptional()
+  @Type(() => BlockFilter)
+  filter?: BlockFilter;
+  @IsEnum(SolanaHandlerKind, {groups: [SolanaHandlerKind.Block]})
+  kind!: SolanaHandlerKind.Block;
+  @IsString()
+  handler!: string;
+}
+
+export class TransactionHandler implements SubqlTransactionHandler {
+  @IsOptional()
+  @ValidateNested()
+  @Type(() => TransactionFilter)
+  filter?: SolanaTransactionFilter;
+  @IsEnum(SolanaHandlerKind, {groups: [SolanaHandlerKind.Transaction]})
+  kind!: SolanaHandlerKind.Transaction;
+  @IsString()
+  handler!: string;
+}
+
+export class InstructionHandler implements SubqlInstructionHandler {
+  @IsOptional()
+  @ValidateNested()
+  @Type(() => InstructionFilter)
+  filter?: SolanaInstructionFilter;
+  @IsEnum(SolanaHandlerKind, {groups: [SolanaHandlerKind.Instruction]})
+  kind!: SolanaHandlerKind.Instruction;
+  @IsString()
+  handler!: string;
+}
+
+export class LogHandler implements SubqlLogHandler {
+  @IsOptional()
+  @ValidateNested()
+  @Type(() => LogFilter)
+  filter?: SolanaLogFilter;
+  @IsEnum(SolanaHandlerKind, {groups: [SolanaHandlerKind.Log]})
+  kind!: SolanaHandlerKind.Log;
+  @IsString()
+  handler!: string;
+}
+
+export class CustomHandler implements SubqlCustomHandler {
+  @IsString()
+  kind!: string;
+  @IsString()
+  handler!: string;
+  @IsObject()
+  @IsOptional()
+  filter?: Record<string, unknown>;
+}
+
+export class SolanaMapping implements SubqlMapping {
+  @Transform((params) => {
+    const handlers: SubqlHandler[] = params.value;
+    return handlers.map((handler) => {
+      switch (handler.kind) {
+        case SolanaHandlerKind.Log:
+          return plainToClass(LogHandler, handler);
+        case SolanaHandlerKind.Instruction:
+          return plainToClass(InstructionHandler, handler);
+        case SolanaHandlerKind.Transaction:
+          return plainToClass(TransactionHandler, handler);
+        case SolanaHandlerKind.Block:
+          return plainToClass(BlockHandler, handler);
+        default:
+          throw new Error(`handler ${(handler as any).kind} not supported`);
+      }
+    });
+  })
+  @IsArray()
+  @ValidateNested()
+  handlers!: SubqlHandler[];
+  @IsString()
+  file!: string;
+}
+
+export class CustomMapping implements SubqlMapping<SubqlCustomHandler> {
+  @IsArray()
+  @Type(() => CustomHandler)
+  @ValidateNested()
+  handlers!: CustomHandler[];
+  @IsString()
+  file!: string;
+}
+
+export class RuntimeDataSourceBase<M extends SubqlMapping<SubqlRuntimeHandler>>
+  extends BaseDataSource
+  implements SubqlRuntimeDatasource<M>
+{
+  @IsEnum(SolanaDatasourceKind, {
+    groups: [SolanaDatasourceKind.Runtime],
+  })
+  kind!: SolanaDatasourceKind.Runtime;
+  @Type(() => SolanaMapping)
+  @ValidateNested()
+  mapping!: M;
+  @Type(() => FileReferenceImpl)
+  @ValidateNested({each: true})
+  @IsOptional()
+  assets?: Map<string, FileReference>;
+}
+
+export class FileReferenceImpl implements FileReference {
+  @IsString()
+  file!: string;
+}
+
+export class CustomDataSourceBase<K extends string, M extends SubqlMapping = SubqlMapping<SubqlCustomHandler>>
+  extends BaseDataSource
+  implements SubqlCustomDatasource<K, M>
+{
+  @IsString()
+  kind!: K;
+  @Type(() => CustomMapping)
+  @ValidateNested()
+  mapping!: M;
+  @Type(() => FileReferenceImpl)
+  @ValidateNested({each: true})
+  assets!: Map<string, FileReference>;
+  @Type(() => FileReferenceImpl)
+  @IsObject()
+  processor!: FileReference;
+}

package/src/project/project.spec.ts

@@ -0,0 +1,123 @@
+// Copyright 2020-2025 SubQuery Pte Ltd authors & contributors
+// SPDX-License-Identifier: GPL-3.0
+
+import fs from 'fs';
+import path from 'path';
+import {loadFromJsonOrYaml, RunnerQueryBaseModel} from '@subql/common';
+import {validateSync} from 'class-validator';
+import {DeploymentV1_0_0, SolanaRunnerNodeImpl, SolanaRunnerSpecsImpl} from '../project/versioned/v1_0_0';
+import {SolanaProjectManifestVersioned, VersionedProjectManifest} from './versioned';
+
+const projectsDir = path.join(__dirname, '../../test');
+
+function loadSolanaProjectManifest(file: string): SolanaProjectManifestVersioned {
+  let manifestPath = file;
+  if (fs.existsSync(file) && fs.lstatSync(file).isDirectory()) {
+    const yamlFilePath = path.join(file, 'project.yaml');
+    const jsonFilePath = path.join(file, 'project.json');
+    if (fs.existsSync(yamlFilePath)) {
+      manifestPath = yamlFilePath;
+    } else if (fs.existsSync(jsonFilePath)) {
+      manifestPath = jsonFilePath;
+    } else {
+      throw new Error(`Could not find project manifest under dir ${file}`);
+    }
+  }
+
+  const doc = loadFromJsonOrYaml(manifestPath);
+  const projectManifest = new SolanaProjectManifestVersioned(doc as VersionedProjectManifest);
+  projectManifest.validate();
+  return projectManifest;
+}
+
+describe('test solana project.yaml', () => {
+  it('could get solana project template name from its deployment', () => {
+    const manifest = loadSolanaProjectManifest(path.join(projectsDir, 'project_1.0.0.yaml'));
+    const deployment = manifest.toDeployment();
+    expect(deployment).toContain('name: Pool');
+  });
+
+  it('could get options in template from its deployment', () => {
+    const manifest = loadSolanaProjectManifest(path.join(projectsDir, 'project_1.0.0.yaml'));
+    const deployment = manifest.toDeployment();
+    expect(deployment).toContain('abi: Pool');
+  });
+});
+
+describe('project.yaml', () => {
+  it('can validate project.yaml', () => {
+    // TODO this should catch a specific error, the file doesn't currently exist
+    throw new Error('Not implemented');
+    expect(() => loadSolanaProjectManifest(path.join(projectsDir, 'project_falsy.yaml'))).toThrow();
+    expect(() => loadSolanaProjectManifest(path.join(projectsDir, 'project_falsy_array.yaml'))).toThrow();
+  });
+
+  it('can fail validation if version not supported', () => {
+    // TODO this should catch a specific error, the file doesn't currently exist
+    throw new Error('Not implemented');
+    expect(() => loadSolanaProjectManifest(path.join(projectsDir, 'project_invalid_version.yaml'))).toThrow('');
+  });
+
+  it('can validate a v1.0.0 project.yaml with templates', () => {
+    expect(() => loadSolanaProjectManifest(path.join(projectsDir, 'project_1.0.0.yaml'))).not.toThrow();
+  });
+
+  it('get v1.0.0 deployment mapping filter', () => {
+    const manifestVersioned = loadSolanaProjectManifest(path.join(projectsDir, 'project_1.0.0.yaml'));
+
+    const deployment = manifestVersioned.asV1_0_0.deployment;
+    const filter = deployment.dataSources[0].mapping.handlers[0].filter;
+    const deploymentString = manifestVersioned.toDeployment();
+    expect(filter).not.toBeNull();
+    expect(deploymentString).toContain('Transfer (address from, address to, uint256 tokenId)');
+  });
+
+  it('can convert genesis hash in v1.0.0 to chainId in deployment', () => {
+    const deployment = loadSolanaProjectManifest(path.join(projectsDir, 'project_1.0.0.yaml')).asV1_0_0.deployment;
+    expect(deployment.network.chainId).not.toBeNull();
+    console.log(deployment.network.chainId);
+  });
+
+  it.skip('can get chainId for deployment', () => {
+    const deployment = loadSolanaProjectManifest(path.join(projectsDir, 'project_1.0.0_chainId.yaml')).asV1_0_0
+      .deployment;
+    expect(deployment.network.chainId).toBe('moonbeamChainId');
+  });
+
+  it('can validate deployment runner versions', () => {
+    const deployment = new DeploymentV1_0_0();
+    const nodeImp = new SolanaRunnerNodeImpl();
+    const queryImp = new RunnerQueryBaseModel();
+    deployment.specVersion = '1.0.0';
+    deployment.runner = new SolanaRunnerSpecsImpl();
+
+    nodeImp.name = '@subql/node-solana';
+    nodeImp.version = '*';
+    deployment.runner.node = nodeImp;
+
+    queryImp.name = '@subql/query';
+    queryImp.version = '0.213.1';
+
+    deployment.runner.query = queryImp;
+
+    const errors = validateSync(deployment.runner, {whitelist: true, forbidNonWhitelisted: true});
+    expect(errors.length).toBe(0);
+  });
+
+  it('can validate a v1.0.0 project.yaml with unsupported runner node', () => {
+    expect(() => loadSolanaProjectManifest(path.join(projectsDir, 'project_1.0.0_bad_runner.yaml'))).toThrow();
+  });
+
+  //TODO, pre-release should be excluded
+  it.skip('can throw error with unsupported runner version', () => {
+    expect(() => loadSolanaProjectManifest(path.join(projectsDir, 'project_1.0.0_bad_runner_version.yaml'))).toThrow();
+  });
+
+  it('can validate a v1.0.0 project.yaml runner and datasource mismatches', () => {
+    expect(() => loadSolanaProjectManifest(path.join(projectsDir, 'project_1.0.0_runner_ds_mismatch.yaml'))).toThrow();
+  });
+
+  it('can fail validation if custom ds missing processor', () => {
+    expect(() => loadSolanaProjectManifest(path.join(projectsDir, 'project_0.2.0_invalid_custom_ds.yaml'))).toThrow();
+  });
+});

package/src/project/types.ts

@@ -0,0 +1,19 @@
+// Copyright 2020-2025 SubQuery Pte Ltd authors & contributors
+// SPDX-License-Identifier: GPL-3.0
+
+import { IProjectManifest } from '@subql/types-core';
+import { SubqlDatasource } from '@subql/types-solana';
+
+// All of these used to be redefined in this file, re-exporting for simplicity
+export {
+  SubqlRuntimeHandler,
+  SubqlCustomHandler,
+  SubqlHandler,
+  SubqlDatasource as SubqlSolanaDataSource,
+  SubqlCustomDatasource as SubqlSolanaCustomDataSource,
+  SubqlDatasourceProcessor,
+  SubqlHandlerFilter,
+} from '@subql/types-solana';
+
+export type ISolanaProjectManifest = IProjectManifest<SubqlDatasource>;
+

package/src/project/utils.ts

@@ -0,0 +1,50 @@
+// Copyright 2020-2025 SubQuery Pte Ltd authors & contributors
+// SPDX-License-Identifier: GPL-3.0
+
+import {
+  SecondLayerHandlerProcessor,
+  SubqlCustomDatasource,
+  SubqlDatasource,
+  SolanaDatasourceKind,
+  SolanaHandlerKind,
+  SubqlRuntimeDatasource,
+  SecondLayerHandlerProcessorArray,
+  SubqlCustomHandler,
+  SubqlMapping,
+} from '@subql/types-solana';
+
+type DefaultFilter = Record<string, unknown>;
+
+export function isBlockHandlerProcessor<E>(
+  hp: SecondLayerHandlerProcessorArray<SolanaHandlerKind, DefaultFilter, unknown>
+): hp is SecondLayerHandlerProcessor<SolanaHandlerKind.Block, DefaultFilter, E> {
+  return hp.baseHandlerKind === SolanaHandlerKind.Block;
+}
+
+export function isTransactionHandlerProcessor<E>(
+  hp: SecondLayerHandlerProcessorArray<SolanaHandlerKind, DefaultFilter, unknown>
+): hp is SecondLayerHandlerProcessor<SolanaHandlerKind.Transaction, DefaultFilter, E> {
+  return hp.baseHandlerKind === SolanaHandlerKind.Transaction;
+}
+
+export function isInstructionHandlerProcessor<E>(
+  hp: SecondLayerHandlerProcessorArray<SolanaHandlerKind, DefaultFilter, unknown>
+): hp is SecondLayerHandlerProcessor<SolanaHandlerKind.Instruction, DefaultFilter, E> {
+  return hp.baseHandlerKind === SolanaHandlerKind.Instruction;
+}
+
+export function isLogHandlerProcessor<E>(
+  hp: SecondLayerHandlerProcessorArray<SolanaHandlerKind, DefaultFilter, unknown>
+): hp is SecondLayerHandlerProcessor<SolanaHandlerKind.Log, DefaultFilter, E> {
+  return hp.baseHandlerKind === SolanaHandlerKind.Log;
+}
+
+export function isCustomDs<F extends SubqlMapping<SubqlCustomHandler>>(
+  ds: SubqlDatasource
+): ds is SubqlCustomDatasource<string, F> {
+  return ds.kind !== SolanaDatasourceKind.Runtime && !!(ds as SubqlCustomDatasource<string>).processor;
+}
+
+export function isRuntimeDs(ds: SubqlDatasource): ds is SubqlRuntimeDatasource {
+  return ds.kind === SolanaDatasourceKind.Runtime;
+}

package/src/project/versioned/ProjectManifestVersioned.ts

@@ -0,0 +1,71 @@
+// Copyright 2020-2025 SubQuery Pte Ltd authors & contributors
+// SPDX-License-Identifier: GPL-3.0
+
+import { plainToClass } from 'class-transformer';
+import { ISolanaProjectManifest, SubqlSolanaDataSource } from '../types';
+import { ProjectManifestV1_0_0Impl } from './v1_0_0';
+export type VersionedProjectManifest = { specVersion: string };
+
+const SOLANA_SUPPORTED_VERSIONS = {
+  '1.0.0': ProjectManifestV1_0_0Impl,
+};
+
+type Versions = keyof typeof SOLANA_SUPPORTED_VERSIONS;
+
+type ProjectManifestImpls = InstanceType<(typeof SOLANA_SUPPORTED_VERSIONS)[Versions]>;
+
+export function manifestIsV1_0_0(manifest: ISolanaProjectManifest): manifest is ProjectManifestV1_0_0Impl {
+  return manifest.specVersion === '1.0.0';
+}
+
+export class SolanaProjectManifestVersioned implements ISolanaProjectManifest {
+  private _impl: ProjectManifestImpls;
+
+  constructor(projectManifest: VersionedProjectManifest) {
+    const klass = SOLANA_SUPPORTED_VERSIONS[projectManifest.specVersion as Versions];
+    if (!klass) {
+      throw new Error('specVersion not supported for project manifest file');
+    }
+    this._impl = plainToClass<ProjectManifestImpls, VersionedProjectManifest>(klass, projectManifest);
+  }
+
+  get asImpl(): ProjectManifestImpls {
+    return this._impl;
+  }
+
+  get isV1_0_0(): boolean {
+    return this.specVersion === '1.0.0';
+  }
+
+  get asV1_0_0(): ProjectManifestV1_0_0Impl {
+    return this._impl as ProjectManifestV1_0_0Impl;
+  }
+
+  toDeployment(): string {
+    return this._impl.deployment.toYaml();
+  }
+
+  validate(): void {
+    return this._impl.validate();
+  }
+
+  get dataSources(): SubqlSolanaDataSource[] {
+    return this._impl.dataSources;
+  }
+
+  get schema(): string {
+    return this._impl.schema.file;
+  }
+
+  get specVersion(): string {
+    return this._impl.specVersion;
+  }
+
+  get description(): string | undefined {
+    return this._impl.description;
+  }
+
+  get repository(): string | undefined {
+    return this._impl.repository;
+  }
+}

package/src/project/versioned/index.ts

@@ -0,0 +1,5 @@
+// Copyright 2020-2025 SubQuery Pte Ltd authors & contributors
+// SPDX-License-Identifier: GPL-3.0
+
+export * from './ProjectManifestVersioned';
+export * from './v1_0_0';

package/src/project/versioned/v1_0_0/index.ts

@@ -0,0 +1,4 @@
+// Copyright 2020-2025 SubQuery Pte Ltd authors & contributors
+// SPDX-License-Identifier: GPL-3.0
+
+export * from './model';