Hints

Helpful Guidance for the GetAccountBalance Implementation

← Back to Workshop

---

General Approach

If you're stuck, try this step-by-step approach:

1. Start small — Get a minimal handler working first

2. Add validation incrementally — One check at a time

3. Test frequently — Verify each addition works

4. Study existing handlers — Copy proven patterns

5. Use helper functions — Don't reinvent the wheel

---

Hint 1: File Structure

Your handler file should follow this structure:

// Copyright and license header
// Include necessary headers
// namespace ripple {
//   Helper functions (if needed)
//   Main handler function
// } // namespace ripple

Essential includes:

• <xrpld/rpc/Context.h> — For JsonContext

• <xrpld/rpc/detail/RPCHelpers.h> — For helper functions

• <xrpl/protocol/ErrorCodes.h> — For error codes

• <xrpl/protocol/jss.h> — For JSON field names

---

Hint 2: Handler Signature

Remember the standard signature:

Json::Value doGetAccountBalance(RPC::JsonContext& context)
{
    Json::Value result;

    // Your implementation here

    return result;
}

Important: Function name should start with do followed by the command name in PascalCase.

---

Hint 3: Account Validation

Use the parseBase58 template function:

auto const account = parseBase58<AccountID>(
    context.params[jss::account].asString()
);

if (!account) {
    return rpcError(rpcACT_MALFORMED, "Invalid account address");
}

// Use *account to get the AccountID value

---

Hint 4: Ledger Lookup

The easiest way to get a ledger:

std::shared_ptr<ReadView const> ledger;
auto const result = RPC::lookupLedger(ledger, context);

if (!ledger) {
    return result;  // This already contains the error
}

// Now 'ledger' is safe to use

This helper automatically:

• Parses ledger_index or ledger_hash from params

• Handles "current", "validated", "closed"

• Returns proper error if not found

---

Hint 5: Reading Account Data

Use the keylet system:

auto const sleAccount = ledger->read(keylet::account(*account));

if (!sleAccount) {
    return rpcError(rpcACT_NOT_FOUND, "Account not found");
}

// sleAccount is a std::shared_ptr<SLE const>

---

Hint 6: Extracting Field Values

Access account fields using type-safe getters:

// Get XRP balance
STAmount balance = sleAccount->getFieldAmount(sfBalance);

// Get sequence number
std::uint32_t sequence = sleAccount->getFieldU32(sfSequence);

// Get owner count
std::uint32_t ownerCount = sleAccount->getFieldU32(sfOwnerCount);

---

Hint 7: Reserve Calculations

Get fee information from the ledger:

auto const& fees = ledger->fees();

// Base reserve (for the account itself)
XRPAmount baseReserve = fees.accountReserve(0);

// Owner reserve (base reserve × owner count)
XRPAmount ownerReserve = fees.accountReserve(ownerCount) - baseReserve;

// Total reserve
XRPAmount totalReserve = baseReserve + ownerReserve;

// Available balance
XRPAmount available = balance.xrp() - totalReserve;

---

Hint 8: Building JSON Responses

Use the jss namespace for standard field names:

result[jss::account] = to_string(*account);
result[jss::ledger_index] = ledger->info().seq;
result[jss::validated] = ledger->isImmutable();

// Custom fields use string literals
result["balance"] = to_string(balance);
result["available_balance"] = to_string(available);

---

Hint 9: Converting Amounts to Strings

Use to_string() for all amount types:

// For STAmount
result["balance"] = to_string(balance);

// For XRPAmount
result["reserve"] = to_string(baseReserve);

// For AccountID
result[jss::account] = to_string(*account);

---

Hint 10: Handler Registration

In Handlers.cpp, add this entry:

{
    "get_account_balance",
    {
        &doGetAccountBalance,
        Role::USER,              // Minimum role required
        RPC::NEEDS_CURRENT_LEDGER  // Conditions
    }
}

Why USER role? This is a read operation, so authenticated users should have access.

Why NEEDS_CURRENT_LEDGER? We need ledger access to query account state.

---

Hint 11: Error Handling Pattern

Follow this pattern for all validations:

// 1. Check if field exists
if (!context.params.isMember(jss::account)) {
    return rpcError(rpcINVALID_PARAMS, "Missing 'account' field");
}

// 2. Check field type
if (!context.params[jss::account].isString()) {
    return rpcError(rpcINVALID_PARAMS, "'account' must be a string");
}

// 3. Validate field value
auto const account = parseBase58<AccountID>(
    context.params[jss::account].asString()
);

if (!account) {
    return rpcError(rpcACT_MALFORMED, "Invalid account address");
}

// 4. Continue processing

---

Hint 12: Testing Setup

Your test file should start like this:

#include <xrpld/rpc/handlers/GetAccountBalance.h>
#include <xrpl/protocol/jss.h>
#include <test/jtx.h>
#include <test/jtx/Env.h>

namespace ripple {
namespace test {

class GetAccountBalance_test : public beast::unit_test::suite
{
public:
    void testValidRequest()
    {
        using namespace jtx;

        Env env(*this);

        // Create account
        Account alice("alice");
        env.fund(XRP(1000), alice);
        env.close();

        // Build request
        Json::Value params;
        params[jss::account] = alice.human();

        // Call handler
        Json::Value result = doGetAccountBalance(/* context */);

        // Verify result
        BEAST_EXPECT(result.isMember("balance"));
        BEAST_EXPECT(result["balance"].asString() == "1000000000");
    }

    void run() override
    {
        testValidRequest();
    }
};

BEAST_DEFINE_TESTSUITE(GetAccountBalance, rpc, ripple);

} // namespace test
} // namespace ripple

---

Hint 13: Common Pitfalls to Avoid

❌ Don't directly access params without checking existence first ✅ Do always check isMember() before accessing

❌ Don't assume ledger is always available ✅ Do use lookupLedger() and check the result

❌ Don't forget to dereference optional values ✅ Do use *account after parsing with parseBase58

❌ Don't return raw exception messages ✅ Do catch exceptions and return proper RPC errors

---

Hint 14: Debugging Tips

If your handler doesn't work:

1. Check compilation errors first

   • Missing includes?

   • Typos in function names?

   • Wrong namespace?

2. Add logging

   JLOG(context.j.debug()) << "Processing account: " << accountStr;

3. Test with rippled command line

   ./rippled get_account_balance '{"account":"rN7n7..."}'

4. Check the handler table

   • Is your handler registered?

   • Is the command name correct (lowercase with underscores)?

---

Hint 15: Reference Code Locations

Look at these files for examples:

Account validation:

• src/xrpld/rpc/handlers/AccountInfo.cpp:44-52

Ledger lookup:

• src/xrpld/rpc/handlers/AccountInfo.cpp:54-60

Reserve calculation:

• src/xrpld/rpc/handlers/AccountInfo.cpp:106-110

Response building:

• src/xrpld/rpc/handlers/AccountInfo.cpp:112-145

---

Still Stuck?

If these hints aren't enough:

1. Compare with AccountInfo — Your handler is very similar

2. Check the test cases — They show expected behavior

3. Ask for help — Use the feedback form

Remember: The goal is to learn, not to finish quickly. Take your time!

---

← Back to Workshop | View Code Snippets →