Initial project setup: Add contracts, API definitions, tests, and documentation

- Add Foundry project configuration (foundry.toml, foundry.lock)
- Add Solidity contracts (TokenFactory138, BridgeVault138, ComplianceRegistry, etc.)
- Add API definitions (OpenAPI, GraphQL, gRPC, AsyncAPI)
- Add comprehensive test suite (unit, integration, fuzz, invariants)
- Add API services (REST, GraphQL, orchestrator, packet service)
- Add documentation (ISO20022 mapping, runbooks, adapter guides)
- Add development tools (RBC tool, Swagger UI, mock server)
- Update OpenZeppelin submodules to v5.0.0

test/api/contract/event-schema-validation.test.ts

@@ -0,0 +1,64 @@
+/**
+ * Event Schema Validation Tests
+ * Ensures events conform to AsyncAPI specification
+ */
+
+import { describe, it, expect } from '@jest/globals';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import * as yaml from 'js-yaml';
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+
+const ASYNCAPI_SPEC = join(__dirname, '../../../api/packages/asyncapi/asyncapi.yaml');
+
+describe('AsyncAPI Event Schema Validation', () => {
+  let asyncapiSpec: any;
+  let ajv: Ajv;
+
+  beforeAll(() => {
+    const specContent = readFileSync(ASYNCAPI_SPEC, 'utf-8');
+    asyncapiSpec = yaml.load(specContent);
+    ajv = new Ajv();
+    addFormats(ajv);
+  });
+
+  it('should have valid AsyncAPI structure', () => {
+    expect(asyncapiSpec).toHaveProperty('asyncapi');
+    expect(asyncapiSpec.asyncapi).toMatch(/^3\.\d+\.\d+$/);
+    expect(asyncapiSpec).toHaveProperty('channels');
+  });
+
+  it('should have all required event channels', () => {
+    const requiredChannels = [
+      'triggers.created',
+      'triggers.state.updated',
+      'liens.placed',
+      'liens.reduced',
+      'liens.released',
+      'packets.generated',
+      'packets.dispatched',
+      'packets.acknowledged',
+      'bridge.locked',
+      'bridge.unlocked',
+      'compliance.updated',
+      'policy.updated',
+    ];
+
+    requiredChannels.forEach((channel) => {
+      expect(asyncapiSpec.channels).toHaveProperty(channel);
+    });
+  });
+
+  it('should have event envelope schema', () => {
+    expect(asyncapiSpec.components).toHaveProperty('schemas');
+    expect(asyncapiSpec.components.schemas).toHaveProperty('EventEnvelope');
+    
+    const envelopeSchema = asyncapiSpec.components.schemas.EventEnvelope;
+    expect(envelopeSchema.required).toContain('eventId');
+    expect(envelopeSchema.required).toContain('eventType');
+    expect(envelopeSchema.required).toContain('occurredAt');
+    expect(envelopeSchema.required).toContain('payload');
+  });
+});
+

test/api/contract/openapi-validation.test.ts

@@ -0,0 +1,62 @@
+/**
+ * OpenAPI Contract Validation Tests
+ * Ensures API implementation conforms to OpenAPI specification
+ */
+
+import { describe, it, expect } from '@jest/globals';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import * as yaml from 'js-yaml';
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+
+const OPENAPI_SPEC = join(__dirname, '../../../api/packages/openapi/v1/openapi.yaml');
+
+describe('OpenAPI Contract Validation', () => {
+  let openapiSpec: any;
+
+  beforeAll(() => {
+    const specContent = readFileSync(OPENAPI_SPEC, 'utf-8');
+    openapiSpec = yaml.load(specContent);
+  });
+
+  it('should have valid OpenAPI structure', () => {
+    expect(openapiSpec).toHaveProperty('openapi');
+    expect(openapiSpec.openapi).toMatch(/^3\.\d+\.\d+$/);
+    expect(openapiSpec).toHaveProperty('info');
+    expect(openapiSpec).toHaveProperty('paths');
+  });
+
+  it('should have all required paths', () => {
+    const requiredPaths = [
+      '/tokens',
+      '/tokens/{code}',
+      '/liens',
+      '/liens/{lienId}',
+      '/compliance/accounts/{accountRefId}',
+      '/triggers',
+      '/triggers/{triggerId}',
+      '/iso/inbound',
+      '/iso/outbound',
+      '/packets',
+      '/bridge/lock',
+      '/bridge/unlock',
+    ];
+
+    requiredPaths.forEach((path) => {
+      expect(openapiSpec.paths).toHaveProperty(path);
+    });
+  });
+
+  it('should have security schemes defined', () => {
+    expect(openapiSpec.components).toHaveProperty('securitySchemes');
+    expect(openapiSpec.components.securitySchemes).toHaveProperty('oauth2');
+    expect(openapiSpec.components.securitySchemes).toHaveProperty('mtls');
+  });
+
+  it('should have idempotency markers', () => {
+    expect(openapiSpec).toHaveProperty('x-idempotency');
+    expect(Array.isArray(openapiSpec['x-idempotency'])).toBe(true);
+  });
+});
+