feat(kotlin): mpp/session client

[EfeDurmaz16]

Adds the client-side MPP payment-channel session intent to the Kotlin SDK (com.solana.paykit), mirroring the Rust reference spine and the Go reference.

What

• paycore PaymentChannels: the 48-byte Ed25519 voucher preimage, channel + event-authority PDA derivation, and the open instruction plus the payer-signed (operator-fee-payer-unsigned) open transaction. Client subset only; the server-side settle/finalize/distribute, the Ed25519 precompile, and the BLAKE3 distribution hash are out of scope for this client-only SDK.
• Session wire types (kotlinx.serialization): SessionRequest, OpenPayload (salt as a decimal string via SaltStringSerializer), SignedVoucher/VoucherData (cumulativeAmount with a cumulative read-alias), commit/topUp/close payloads, MeteringDirective/MeteringUsage, CommitReceipt, and the SessionAction sealed union with the SessionActionCodec flatten/unflatten codec (the action key, the topUp tag).
• ActiveSession: monotonic cumulative watermark, nonce accounting, retry-safe prepare/record voucher, the reconcileSettled lost-response clamp (Go parity), and the action builders. recordVoucher binds the voucher to the active channel and advances the nonce to at least nonce + 1, matching Go RecordVoucher.
• SessionConsumer: validate, sign, commit, advance. The local watermark advances only on a committed receipt and reconciles (clamped to the prepared voucher, never regressing) on a replayed one.
• Session credential framing (serializeSessionCredential, reusing the existing JCS canonicalization) and a solana/session challenge dispatch.

Verification

• gradle check is green (tests, jacoco coverage gate, ktlint).
• Adds a cross-SDK conformance runner: harness/kotlin-conformance (a small gradle application that path-includes the SDK, mirroring harness/kotlin-client) reads a vector on stdin and drives the real PaymentChannels.voucherMessageBytes, registered via harness/runners/kotlin.json with intents=["session"]. Both frozen session-voucher vectors pass through the cross-SDK conformance driver (byte-identical to Swift and Go), now enforced in CI in the harness-kotlin job.

Notes

• Client-only. The session reuses the MPP charge mint resolver (localnet USDC resolves to the mainnet mint); server-side operability caveats are not applicable.

[greptile-apps]

Greptile Summary

This PR introduces the Kotlin MPP payment-channel session client, adding PaymentChannels (48-byte voucher preimage, PDA derivation, open instruction/transaction), ActiveSession (monotonic watermark, nonce accounting, two-phase prepare/record), SessionConsumer (validate-sign-commit-advance), the full session wire type set, SessionActionCodec, and a cross-SDK conformance harness. All new code is backed by unit tests and a pinned conformance vector.

• PaymentChannels implements voucher preimage serialization, channel PDA derivation, and the payer-partial-signed open transaction — all faithfully mirroring the Rust/Go reference.
• ActiveSession / SessionConsumer implement the monotonic watermark with retry-safe prepare/record and the reconcileSettled lost-response clamp (Go fix(rust): do not advance session watermark on a replayed commit #162 parity).
• SessionActionCodec provides a custom flatten/unflatten codec for the internally-tagged SessionAction union, including the camelCase topUp tag and the salt decimal-string serializer.

Confidence Score: 5/5

Safe to merge. Core session logic is correct, well-tested, and faithfully mirrors the Go reference including the reconcileSettled lost-response clamp.

The implementation is clean with comprehensive unit tests covering the two-phase prepare/record flow, replay deduplication, watermark non-regression, and cross-SDK conformance vectors. The one finding is a future-proofing gap in the exhaustiveness of a when statement that has no impact on the current two-value enum.

No files require special attention. SessionConsumer.kt has a non-exhaustive when nit but it has no current behavioral impact.

Important Files Changed

Filename	Overview
kotlin/src/main/kotlin/com/solana/paykit/protocols/mpp/client/SessionConsumer.kt	Core metered-delivery consumer; non-exhaustive when over CommitStatus in commitDirective could silently skip watermark advance for future status values
kotlin/src/main/kotlin/com/solana/paykit/paycore/PaymentChannels.kt	New file: PDA derivation, voucher preimage, and open transaction builder. Correct little-endian encoding and overflow/nonce guards.
kotlin/src/main/kotlin/com/solana/paykit/protocols/mpp/client/SessionClient.kt	New file: ActiveSession (two-phase voucher, watermark, overflow guard), PaymentChannelSession.open, credential serialization. Logic aligns with Go reference.
kotlin/src/main/kotlin/com/solana/paykit/protocols/mpp/core/SessionTypes.kt	New file: full wire-type set. SaltStringSerializer correctly uses element.content.toULongOrNull() to handle the full u64 range.
kotlin/src/main/kotlin/com/solana/paykit/protocols/mpp/core/SessionActionCodec.kt	Flatten/unflatten codec for internally-tagged SessionAction union; camelCase topUp tag handled correctly.
kotlin/examples/AndroidDemo/app/src/main/java/com/solana/paykit/demo/SessionStream.kt	Demo end-to-end session flow. HttpCommitTransport throws IllegalStateException on failure rather than MppException; correctness preserved but exception type diverges from SDK contract.
harness/kotlin-conformance/src/main/kotlin/com/solana/paykit/conformance/Main.kt	Cross-SDK conformance harness correctly drives PaymentChannels.voucherMessageBytes for byte-exact vector verification.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Client
    participant PaymentChannelSession
    participant ActiveSession
    participant SessionConsumer
    participant Transport
    participant Operator

    Client->>PaymentChannelSession: open(request, payerSigner, sessionSigner, blockhash)
    PaymentChannelSession->>PaymentChannelSession: deriveOpen() → channelPDA, salt, deposit
    PaymentChannelSession->>PaymentChannelSession: buildOpenTransaction() → payer-partial-signed tx
    PaymentChannelSession-->>Client: "PaymentChannelSessionOpen { open, session, action }"

    Client->>PaymentChannelSession: serializeSessionCredential(challenge, action)
    PaymentChannelSession-->>Client: Authorization: Payment base64url(JCS)

    Client->>Operator: credential → server co-signs + broadcasts open tx
    Operator-->>Client: 200 SSE stream with MeteringDirective per delivery

    loop Per metered delivery
        Client->>SessionConsumer: commitDirective(directive)
        SessionConsumer->>SessionConsumer: validateDirective()
        SessionConsumer->>ActiveSession: prepareIncrement(amount) → SignedVoucher
        SessionConsumer->>Transport: commit(directive, CommitPayload)
        Transport-->>SessionConsumer: "CommitReceipt { status: COMMITTED | REPLAYED }"
        alt COMMITTED
            SessionConsumer->>ActiveSession: recordVoucher(voucher) → advance watermark + nonce
        else REPLAYED
            SessionConsumer->>ActiveSession: reconcileSettled(min(settled, prepared))
        end
        SessionConsumer-->>Client: CommitReceipt
    end

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Client
    participant PaymentChannelSession
    participant ActiveSession
    participant SessionConsumer
    participant Transport
    participant Operator

    Client->>PaymentChannelSession: open(request, payerSigner, sessionSigner, blockhash)
    PaymentChannelSession->>PaymentChannelSession: deriveOpen() → channelPDA, salt, deposit
    PaymentChannelSession->>PaymentChannelSession: buildOpenTransaction() → payer-partial-signed tx
    PaymentChannelSession-->>Client: "PaymentChannelSessionOpen { open, session, action }"

    Client->>PaymentChannelSession: serializeSessionCredential(challenge, action)
    PaymentChannelSession-->>Client: Authorization: Payment base64url(JCS)

    Client->>Operator: credential → server co-signs + broadcasts open tx
    Operator-->>Client: 200 SSE stream with MeteringDirective per delivery

    loop Per metered delivery
        Client->>SessionConsumer: commitDirective(directive)
        SessionConsumer->>SessionConsumer: validateDirective()
        SessionConsumer->>ActiveSession: prepareIncrement(amount) → SignedVoucher
        SessionConsumer->>Transport: commit(directive, CommitPayload)
        Transport-->>SessionConsumer: "CommitReceipt { status: COMMITTED | REPLAYED }"
        alt COMMITTED
            SessionConsumer->>ActiveSession: recordVoucher(voucher) → advance watermark + nonce
        else REPLAYED
            SessionConsumer->>ActiveSession: reconcileSettled(min(settled, prepared))
        end
        SessionConsumer-->>Client: CommitReceipt
    end

Loading

_{Reviews (8): Last reviewed commit: "feat(kotlin/example): consume the sessio..." | Re-trigger Greptile}

[greptile-apps]

The number branch of SaltStringSerializer uses JsonPrimitive.longOrNull to read the salt. Any salt value greater than Long.MAX_VALUE (~9.2 × 10¹⁸) will cause longOrNull to return null, which throws InvalidJson. Since salt is a random u64, about half of all valid salts would silently break deserialization if a peer sends them as a JSON number rather than a string. Using content.toULongOrNull() on the primitive's raw string avoids the Long range limit entirely.

Suggested change

	} else {
	element.longOrNull?.toULong() ?: throw MppException.InvalidJson()
	}
	} else {
	element.content.toULongOrNull() ?: throw MppException.InvalidJson()
	}