[Intermediate]: Implement `appendFile` TCK endpoint

[rwalworth]

🧩 Intermediate Friendly

This issue is a good fit for contributors who are already familiar with the Hiero C++ SDK and feel comfortable navigating the codebase.

Intermediate Issues often involve:

• Exploring existing implementations
• Understanding how different components work together
• Making thoughtful changes that follow established patterns

The goal is to support deeper problem-solving while keeping the task clear, focused, and enjoyable to work on.

Important

🧭 About Intermediate Issues

Intermediate Issues are a great next step for contributors who enjoy
digging into the codebase and reasoning about how things work.

These issues often:

• Involve multiple related files or components
• Encourage investigation and understanding of existing behavior
• Leave room for thoughtful implementation choices
• Stay focused on a clearly defined goal

Other kinds of contributions — from beginner-friendly tasks to large
system-level changes — are just as valuable and use different labels.

---

🐞 Problem Description

The TCK (Test Compatibility Kit) server in this repository exposes JSON-RPC endpoints that the hiero-sdk-tck test suite calls to verify SDK behavior across all Hiero SDKs.

The FileService currently implements createFile, deleteFile, and updateFile, but is missing the appendFile endpoint. The TCK test file test-file-append-transaction.ts calls this method and cannot run against this C++ SDK until it is implemented.

The full TCK specification for this endpoint — including all input/output parameters, test cases, and example JSON-RPC requests — is published here:

FileAppendTransaction — TCK Test Specification

The SDK already has a fully implemented FileAppendTransaction class in src/sdk/main/include/FileAppendTransaction.h. This issue is about wiring up that existing class to the TCK server.

What makes this interesting: Unlike the other FileService transaction endpoints, FileAppendTransaction extends ChunkedTransaction rather than Transaction. This introduces two additional parameters (maxChunks and chunkSize) that require using methods inherited from ChunkedTransaction.

---

💡 Expected Outcome

The TCK server should respond to a new appendFile JSON-RPC method. The full input/output parameter specification is defined in the TCK docs. In summary:

Inputs: fileId, contents, maxChunks, chunkSize, commonTransactionParams (all optional except contents)

Output: { "status": "..." } — the status string from the TransactionReceipt

The implementation should:

• Follow the existing patterns in FileService.cc for transaction endpoints
• Use FileAppendTransaction from the SDK
• Support maxChunks and chunkSize via ChunkedTransaction::setMaxChunks(unsigned int) and ChunkedTransaction::setChunkSize(unsigned int)
• Accept commonTransactionParams using the existing CommonTransactionParams::fillOutTransaction template
• Not modify any existing endpoints or SDK behavior

---

🧠 Implementation Notes

Architecture

Each TCK endpoint has four parts:

1. Params struct — a header in src/tck/include/file/params/ that defines the JSON-RPC parameters and their deserialization
2. Service header — a function declaration in src/tck/include/file/FileService.h
3. Service implementation — the function body in src/tck/src/file/FileService.cc
4. Server registration — wiring in src/tck/src/TckServer.cc (include, addMethod call, template instantiation)

Reference implementations

What you're building	Closest existing reference
AppendFileParams struct	src/tck/include/file/params/UpdateFileParams.h (similar transaction params pattern, but replace file-specific fields with contents, maxChunks, chunkSize)
appendFile function	updateFile in src/tck/src/file/FileService.cc (line 105) — same pattern, but uses FileAppendTransaction and adds chunking parameters
ChunkedTransaction methods	src/sdk/main/include/ChunkedTransaction.h — provides setMaxChunks(unsigned int) and setChunkSize(unsigned int)

Things to think about

• ChunkedTransaction compatibility: FileAppendTransaction inherits from ChunkedTransaction<FileAppendTransaction> which extends Transaction<FileAppendTransaction>. The CommonTransactionParams::fillOutTransaction template accepts Transaction<T>&, so it should work. Verify this compiles.

• Content setting: FileAppendTransaction provides setContents(std::string_view) which accepts a string directly — no byte conversion needed.

• Parameter types: The TCK spec sends maxChunks and chunkSize as numbers. The params struct should use std::optional<int> or similar, and cast to unsigned int when calling the SDK methods.

Files to create and modify

File	Action
src/tck/include/file/params/AppendFileParams.h	Create — params struct with mFileId, mContents, mMaxChunks, mChunkSize, mCommonTxParams
src/tck/include/file/FileService.h	Edit — add forward declaration and function declaration
src/tck/src/file/FileService.cc	Edit — add appendFile implementation
src/tck/src/TckServer.cc	Edit — add include, register method, add template instantiation

Key SDK headers to study

File	What to learn
src/sdk/main/include/FileAppendTransaction.h	setFileId, setContents(std::string_view), inherited setMaxChunks/setChunkSize
src/sdk/main/include/ChunkedTransaction.h	setMaxChunks(unsigned int) (line 241), setChunkSize(unsigned int) (line 249)
src/tck/include/common/CommonTransactionParams.h	fillOutTransaction template — works with Transaction<T>&

---

✅ Acceptance Criteria

To help get this change merged smoothly:

• Endpoint: appendFile is registered in TckServer and responds to JSON-RPC calls
• Parameters: Correctly deserializes fileId, contents, maxChunks, chunkSize, and commonTransactionParams
• Chunking: maxChunks and chunkSize are passed through to ChunkedTransaction methods
• Pattern: Implementation follows the same structure as existing FileService endpoints
• Behavior: No changes to existing endpoints or SDK behavior
• Build: Project compiles successfully
• Tests: Existing CI checks pass
• Review: All code review feedback addressed

---

📋 Contribution Guide

To help your contribution go as smoothly as possible, we recommend following these steps:

• Comment /assign to request the issue
• Wait for assignment
• Fork the repository and create a branch
• Set up the project using the instructions in README.md
• Make the requested changes
• Sign each commit using -s -S
• Push your branch and open a pull request

Read Workflow Guide for step-by-step workflow guidance.
Read README.md for setup instructions.

❗ Pull requests cannot be merged without S and s signed commits.
See the Signing Guide.

---

📚 Additional Context or Resources

• FileAppendTransaction — TCK Test Specification — full input/output parameters, test cases, and JSON-RPC examples
• Common Transaction Parameters — TCK Docs — the commonTransactionParams object specification

If you have questions, the community is happy to help:

Hiero-SDK-C++ Discord

[rwalworth]

Closed in #1252.