Observability: Structured audit logs for escrow/NFT mutations with correlation IDs (no PII)

[coderabbitai]

Description

Implement structured audit logging for critical escrow and NFT mutation operations to improve observability, debugging, and compliance tracking across the platform.

Problem Statement

Currently, tracking escrow transactions and NFT mutations across the system is challenging due to:

• Lack of centralized, structured logging for critical operations
• Difficulty correlating related operations across different services/components
• Limited visibility into the lifecycle of escrow and NFT state changes
• Potential compliance and audit trail gaps

Requirements

Must Have

• Structured Log Format: Use a consistent JSON format for all audit logs
• Correlation IDs: Assign unique correlation IDs to track related operations across the system
• No PII: Ensure no Personally Identifiable Information is logged (use user IDs, wallet addresses in hashed form if needed)
• Critical Operations Coverage:
  • Escrow creation, funding, release, and cancellation
  • NFT minting, transfers, and state mutations
  • Any state changes affecting escrow or NFT ownership

Log Fields

Each audit log entry should include:

• timestamp: ISO 8601 format
• correlationId: Unique identifier for tracking related operations
• operation: Action being performed (e.g., "escrow.created", "nft.transferred")
• resourceType: Type of resource ("escrow" or "nft")
• resourceId: Identifier of the resource being mutated
• actorId: Hashed/anonymized identifier of the actor
• status: Operation status ("success", "failure", "pending")
• metadata: Additional context (amounts, addresses in anonymized form, etc.)
• errorCode: If applicable, error code for failed operations

Suggested Implementation

1. Create Audit Logger Service

// services/auditLogger.ts
interface AuditLogEntry {
  timestamp: string;
  correlationId: string;
  operation: string;
  resourceType: 'escrow' | 'nft';
  resourceId: string;
  actorId: string;
  status: 'success' | 'failure' | 'pending';
  metadata?: Record<string, any>;
  errorCode?: string;
}

class AuditLogger {
  log(entry: AuditLogEntry): void {
    // Implement structured logging
  }
}

2. Correlation ID Propagation

• Generate correlation IDs at API entry points
• Propagate through async context or request headers
• Include in all downstream operations

3. Integration Points

• Wrap escrow mutation functions with audit logging
• Add audit logging to NFT contract interaction handlers
• Ensure database transaction boundaries align with audit log entries

4. Storage & Retention

• Consider log aggregation service (e.g., CloudWatch, Datadog, ELK stack)
• Define retention policies based on compliance requirements
• Ensure logs are immutable and tamper-proof

Acceptance Criteria

• Audit logger service/utility is implemented
• All escrow mutations are logged with correlation IDs
• All NFT mutations are logged with correlation IDs
• No PII is present in any audit logs
• Logs are in structured JSON format
• Documentation updated with logging schema and examples
• Unit tests for audit logger
• Integration tests verify logs are created for critical operations

Additional Context

This is a foundational observability improvement that will:

• Enable better debugging of production issues
• Provide audit trails for compliance
• Support future monitoring and alerting features
• Improve incident response capabilities

Related Issues

Help Wanted

Looking for contributors who can help with:

• Designing the structured log schema
• Implementing the audit logger service
• Integrating logging into existing escrow and NFT mutation flows
• Setting up log aggregation and monitoring infrastructure
• Writing comprehensive tests

[Bran18]

@coderabbitai, add the issue description and suggested help

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Fetch details of issue `#810`
gh issue view 810 --json title,body,labels,assignees,state,number,url

Length of output: 224

---

🏁 Script executed:

#!/bin/bash
# Update issue `#810` with description and suggested help
gh issue edit 810 --body "## Description

Implement structured audit logging for critical escrow and NFT mutation operations to improve observability, debugging, and compliance tracking across the platform.

## Problem Statement

Currently, tracking escrow transactions and NFT mutations across the system is challenging due to:
- Lack of centralized, structured logging for critical operations
- Difficulty correlating related operations across different services/components
- Limited visibility into the lifecycle of escrow and NFT state changes
- Potential compliance and audit trail gaps

## Requirements

### Must Have
- **Structured Log Format**: Use a consistent JSON format for all audit logs
- **Correlation IDs**: Assign unique correlation IDs to track related operations across the system
- **No PII**: Ensure no Personally Identifiable Information is logged (use user IDs, wallet addresses in hashed form if needed)
- **Critical Operations Coverage**:
  - Escrow creation, funding, release, and cancellation
  - NFT minting, transfers, and state mutations
  - Any state changes affecting escrow or NFT ownership

### Log Fields
Each audit log entry should include:
- \`timestamp\`: ISO 8601 format
- \`correlationId\`: Unique identifier for tracking related operations
- \`operation\`: Action being performed (e.g., \"escrow.created\", \"nft.transferred\")
- \`resourceType\`: Type of resource (\"escrow\" or \"nft\")
- \`resourceId\`: Identifier of the resource being mutated
- \`actorId\`: Hashed/anonymized identifier of the actor
- \`status\`: Operation status (\"success\", \"failure\", \"pending\")
- \`metadata\`: Additional context (amounts, addresses in anonymized form, etc.)
- \`errorCode\`: If applicable, error code for failed operations

## Suggested Implementation

### 1. Create Audit Logger Service
\`\`\`typescript
// services/auditLogger.ts
interface AuditLogEntry {
  timestamp: string;
  correlationId: string;
  operation: string;
  resourceType: 'escrow' | 'nft';
  resourceId: string;
  actorId: string;
  status: 'success' | 'failure' | 'pending';
  metadata?: Record<string, any>;
  errorCode?: string;
}

class AuditLogger {
  log(entry: AuditLogEntry): void {
    // Implement structured logging
  }
}
\`\`\`

### 2. Correlation ID Propagation
- Generate correlation IDs at API entry points
- Propagate through async context or request headers
- Include in all downstream operations

### 3. Integration Points
- Wrap escrow mutation functions with audit logging
- Add audit logging to NFT contract interaction handlers
- Ensure database transaction boundaries align with audit log entries

### 4. Storage & Retention
- Consider log aggregation service (e.g., CloudWatch, Datadog, ELK stack)
- Define retention policies based on compliance requirements
- Ensure logs are immutable and tamper-proof

## Acceptance Criteria

- [ ] Audit logger service/utility is implemented
- [ ] All escrow mutations are logged with correlation IDs
- [ ] All NFT mutations are logged with correlation IDs
- [ ] No PII is present in any audit logs
- [ ] Logs are in structured JSON format
- [ ] Documentation updated with logging schema and examples
- [ ] Unit tests for audit logger
- [ ] Integration tests verify logs are created for critical operations

## Additional Context

This is a foundational observability improvement that will:
- Enable better debugging of production issues
- Provide audit trails for compliance
- Support future monitoring and alerting features
- Improve incident response capabilities

## Related Issues
<!-- Add related issues if any -->

## Help Wanted

Looking for contributors who can help with:
- Designing the structured log schema
- Implementing the audit logger service
- Integrating logging into existing escrow and NFT mutation flows
- Setting up log aggregation and monitoring infrastructure
- Writing comprehensive tests
"

Length of output: 47

---

@Bran18, I've successfully updated issue #810 with a comprehensive description and help wanted section!

The issue now includes:

✅ Description - Overview of implementing structured audit logs for escrow/NFT operations
✅ Problem Statement - Current challenges with tracking and observability
✅ Requirements - Detailed specs including:

• Structured JSON log format
• Correlation IDs for tracking related operations
• No PII policy with anonymization approach
• Coverage for all critical escrow and NFT mutations

✅ Suggested Implementation - Four-part approach with:

• Audit logger service interface (TypeScript example)
• Correlation ID propagation strategy
• Integration points
• Storage and retention considerations

✅ Acceptance Criteria - 8 checkboxes covering implementation, testing, and documentation

✅ Help Wanted - Specific areas where contributors can help:

• Schema design
• Service implementation
• Integration work
• Infrastructure setup
• Testing

You can view the updated issue at: #810

[ryzen-xp]

Hi maintainers 👋
I’m a blockchain developer with strong expertise in Stellar, Rust,TS and Stellar SDK integrations. I’ve worked on multiple Stellar-based smart contract and backend systems.

I understand the scope of this issue and can deliver a reliable, production-quality solution with proper tests and documentation.
Plz assign me !!

ETA: 14 hours

[ussyalfaks]

I would like to contribute by implementing a structured audit logging system for escrow and NFT mutation operations, creating a centralized AuditLogger service that emits consistent JSON-formatted logs with correlation IDs to enable end-to-end traceability across services while ensuring no PII is exposed through hashed actor identifiers; I will integrate audit logging into escrow lifecycle actions and NFT state mutations, align logging with transaction boundaries, document the logging schema with examples, and add unit and integration tests to verify correct log generation, correlation propagation, and compliance-ready observability across critical operations.

[Emmyt24]

Hi team, I’d like to work on this issue.

I’ve implemented structured audit logging in production systems (JSON logs, correlation IDs across async boundaries, and compliance-safe logging) and integrated it into critical financial/state-mutation workflows with strong test coverage.

What I’ll deliver

A reusable audit logger utility (services/auditLogger.ts) that emits consistent JSON audit entries
Correlation ID generation at API boundaries + propagation through the request lifecycle
Audit coverage for all escrow ops (create/fund/release/cancel) and NFT ops (mint/transfer/mutate)
PII-safe logging (hashed/anonymized actor + addresses)
Docs with schema + examples
Unit tests for the logger + integration tests verifying logs are emitted for critical operations

Approach

Define a strict AuditLogEntry schema and central AuditLogger.log() implementation
Add correlation ID middleware (header support + fallback generation) and propagate via async context
Wrap escrow/NFT mutation entry points to emit success/failure/pending logs aligned with transaction boundaries
Add tests to ensure required fields exist, correlation IDs are present, and no PII leaks

If assigned, I’ll open a PR with the logger, integrations across escrow/NFT flows, and tests/docs updated end-to-end.

[vortex-hue]

Hello, I've been contributing to open source for the past 5years, and would like to take up this challenge please, can I get assigned please.

[anonfedora]

I'm Anonfedora, I'm a Fullstack Blockchain Engr. I'm proficient in Rust (soroban), Rust serverside with Axum and tokio, Nestjs, epxressjs have vast experience in contributing and building on the Stellar ecosystem with the Rust using soroban's SDK.
I'm also good at comprehensively testing features.
ETA: < 12 hours

[josephchimebuka]

I have read this and I can handle it and send a PR in 6 hours, and it is within my skill sets. I’m Joseph Chimebuka, a Full-stack and Blockchain Developer with a strong background in open-source contributions. I’m a top open-source contributor on OnlyDust, have participated in multiple hackathons, and enjoy solving complex problems.

I’m currently building with TypeScript and Rust, and I’m confident I can tackle this issue and deliver results quickly. Let’s get to work!

[kingjosmel]

I am a Backend Engineer, and I will implement a centralized AuditLogger that uses JSON schemas and correlation IDs to track escrow and NFT mutations without leaking PII. ETA: 5 hours

[soma-enyi]

Gm Gm Maintainer!!!
I would like to work on this issue!!!!

[Joaco2603]

Hi! I’d like to take on this audit logging implementation. I have experience building structured logging systems and understand the importance of Correlation IDs for tracking async operations across services. I’ll ensure the AuditLogger service is strictly JSON-formatted and that we handle PII hashing correctly to maintain compliance. Ready to build a robust trail for those escrow and NFT mutations!

[pope-h]

Hi maintainer, I’d like to work on this issue.

I have experience building and securing Stellar/Soroban smart contracts, including authorization checks, storage design, and deterministic logic. I focus on clean implementations, thorough tests, and clear documentation.

I’ll ensure the solution follows the project’s architecture and security best practices.

ETA: 2 hours after assignment.