[Feat] Java implementation #178

stefanoamorelli · 2025-05-15T17:03:28Z

Tip

Better reviewed commit-by-commit. This PR follows conventional, atomic commits.

In this PR we introduce the Java implementation + tests (>85% test coverage), following the existing typescript, and go implementations.

A follow-up PR will include a more extensive Java Spring example.

Closes: #164

vercel · 2025-05-15T17:03:34Z

Someone is attempting to deploy a commit to the Coinbase Team on Vercel.

A member of the Team first needs to authorize it.

cb-heimdall · 2025-05-15T17:03:35Z

✅ Heimdall Review Status

Requirement Status More Info

Reviews

✅ 1/1

Denominator calculation

Show calculation

1 if user is bot 0

1 if user is external 0

2 if repo is sensitive 0

From .codeflow.yml 1

Additional review requirements

Show calculation

Max	0

0

From CODEOWNERS 0

Global minimum 0

Max 1

1

1 if commit is unverified 0

Sum 1

erikreppel-cb · 2025-05-15T20:31:24Z

@stefanoamorelli amazingly quick turn around, will review. We need you to sign your commits before we merge https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits

stefanoamorelli · 2025-05-16T10:06:08Z

@stefanoamorelli amazingly quick turn around, will review. We need you to sign your commits before we merge https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits

Authored, signed the commits, and rebased ✅

erikreppel-cb · 2025-05-26T17:08:56Z

@stefanoamorelli apologies for the delay, CB has been on recharge week. I'm not very versed in Java so gonna have someone from our team who is take a look, should merge this week.

Your commits still aren't showing up as signed, do need that or I physically can't merge :)

stefanoamorelli · 2025-05-26T17:24:53Z

@erikreppel-cb no worries, thanks for letting me know!

I've force-pushed the signed commits, does it show on your end too now?

And sure, looking forward to your feedback!

erikreppel-cb · 2025-05-27T01:10:05Z

@stefanoamorelli yes now they're signed, thank you!

yuga-cb · 2025-05-27T13:34:13Z

java/checkstyle-suppressions.xml

+  <suppress checks="VisibilityModifier" files=".*[/\\]client[/\\].*\.java"/>
+
+  <!-- Suppress indentation checks on all files -->
+  <suppress checks="Indentation" files=".*\.java"/>


Why do we suppress this?

No need actually, removed.

yuga-cb · 2025-05-27T13:36:45Z

java/checkstyle.xml

+    <module name="IllegalInstantiation"/>
+    <module name="SimplifyBooleanExpression"/>
+    <module name="SimplifyBooleanReturn"/>
+


Consider adding a Javadoc checker to ensure documentation, e.g.:

Suggested change

<module name="JavadocPackage"/> <module name="MissingJavadocType"> <property name="scope" value="public"/> <property name="excludeScope" value="package"/> </module>

<module name="MissingJavadocMethod"> <property name="scope" value="public"/>

<property name="excludeScope" value="package"/>

<property name="allowMissingPropertyJavadoc" value="true"/> </module>

<module name="MissingJavadocVariable"> <property name="scope" value="public"/>

</module>

<module name="JavadocStyle"> <property name="checkFirstSentence" value="true"/>

<property name="endOfSentenceFormat" value="([.?!][ \t\n\r\f<])|([.?!]$)"/>

<property name="checkEmptyJavadoc" value="true"/>

<property name="checkHtml" value="true"/>

</module>

yuga-cb · 2025-05-27T13:44:45Z

java/src/main/java/com/coinbase/x402/client/HttpFacilitatorClient.java

+                        Json.MAPPER.writeValueAsString(body)))
+                .build();
+
+        String json = http.send(request, HttpResponse.BodyHandlers.ofString()).body();


Calling .body() directly means we don't do any error handling - feels like we should catch some common cases? CC @erikreppel-cb

yuga-cb · 2025-05-27T13:46:29Z

java/src/main/java/com/coinbase/x402/crypto/CryptoSigner.java

+ *  Implement with web3j, Solana-J, etc., depending on your payment scheme.
+ */
+public interface CryptoSigner {
+    /** Returns a hex-encoded signature covering the given payload map. */


Could we expand on this Javadoc? It's a bit too abstract to reasonably implement, since interpretations will vary depending on protocol (Ethereum, Solana, etc.)

I've added a more descriptive Javadoc, please let me know if we want more details or a different structure.

yuga-cb · 2025-05-27T13:47:05Z

java/src/main/java/com/coinbase/x402/client/FacilitatorClient.java

+
+/** Contract for calling an x402 facilitator (HTTP, gRPC, mock, etc.). */
+public interface FacilitatorClient {
+    VerificationResponse verify(String paymentHeader,


We should add Javadoc to all public methods

yuga-cb · 2025-05-27T13:47:33Z

java/src/main/java/com/coinbase/x402/client/Kind.java

+
+/** Identifies a payment scheme+network pair that a facilitator supports. */
+public class Kind {
+    public String scheme;    // e.g. "exact"


All of these should be public final since they are read only

yuga-cb · 2025-05-27T13:50:38Z

java/src/main/java/com/coinbase/x402/server/PaymentFilter.java

+    private final Map<String, BigInteger>      priceTable;   // path → amount
+    private final FacilitatorClient            facilitator;
+
+    public PaymentFilter(String payTo,


Javadoc these params. priceTable especially needs a detailed description since it dictates the behavior

yuga-cb · 2025-05-27T13:51:44Z

java/README.md

+    Server->>Facilitator: Settle payment (async)
+```
+
+## Error Handling


We don't do any error handling for non-402 cases?

Updated ✔️

yuga-cb · 2025-05-27T13:51:57Z

java/src/main/java/com/coinbase/x402/server/PaymentFilter.java

+        /* -------- best-effort async settlement (errors ignored) -------- */
+        try {
+            facilitator.settle(header, buildRequirements(path));
+        } catch (Exception ignored) { }


We don't do any error handling for non-402 cases?

Impoved error handling - most importantly, removed the best-effort settlement to align with the typescript and go counterparties and indeed handle settlement failures.

erikreppel-cb · 2025-05-28T20:01:16Z

@stefanoamorelli looks great, your recent commits aren't showing up as signed, if you can sign those I'll merge

Signed-off-by: Stefano Amorelli <stefano@amorelli.tech>

…oSigner

stefanoamorelli · 2025-05-28T20:12:06Z

@erikreppel-cb good stuff, thanks! 🎉 Commits should be signed now, sorry about that ✔️ (I think when re-basing from Github UI they lose their signature)

stefanoamorelli · 2025-06-02T23:02:14Z

@erikreppel-cb just checking in, should I rebase or is there anything needed from my side before merging?

erikreppel-cb · 2025-06-02T23:04:54Z

@stefanoamorelli merged!

stefanoamorelli force-pushed the feat/java branch from 0d434c1 to 55bc81b Compare May 15, 2025 17:51

stefanoamorelli mentioned this pull request May 15, 2025

Feature Request: Add Java Implementation #164

Closed

stefanoamorelli force-pushed the feat/java branch 4 times, most recently from c79fa24 to eb86718 Compare May 16, 2025 10:05

stefanoamorelli force-pushed the feat/java branch 3 times, most recently from 0ac9bef to 010bcec Compare May 25, 2025 19:54

stefanoamorelli force-pushed the feat/java branch from 010bcec to 26e6dc1 Compare May 26, 2025 17:18

yuga-cb reviewed May 27, 2025

View reviewed changes

stefanoamorelli force-pushed the feat/java branch 4 times, most recently from 2af4568 to a9b495f Compare May 27, 2025 20:43

stefanoamorelli added 22 commits May 28, 2025 23:09

chore(java): .gitignore

e7daa42

Signed-off-by: Stefano Amorelli <stefano@amorelli.tech>

chore(java): project object model

0c41f52

Signed-off-by: Stefano Amorelli <stefano@amorelli.tech>

chore(java): check style rules

dd19ecf

Signed-off-by: Stefano Amorelli <stefano@amorelli.tech>

chore(java): check style rule suppressions

8d4bf63

Signed-off-by: Stefano Amorelli <stefano@amorelli.tech>

chore(java): spotbugs exclude rules

39196e9

Signed-off-by: Stefano Amorelli <stefano@amorelli.tech>

feat(java): json util function

580f240

Signed-off-by: Stefano Amorelli <stefano@amorelli.tech>

feat(java): implement payment payload model

c176593

Signed-off-by: Stefano Amorelli <stefano@amorelli.tech>

feat(java): implement payment required response

77eeb79

Signed-off-by: Stefano Amorelli <stefano@amorelli.tech>

feat(java): implement payment requirements model

ff3ef4e

Signed-off-by: Stefano Amorelli <stefano@amorelli.tech>

feat(java): implement draft crypto signer interface

406865a

Signed-off-by: Stefano Amorelli <stefano@amorelli.tech>

feat(java): implement payment kind class

49ed01b

Signed-off-by: Stefano Amorelli <stefano@amorelli.tech>

feat(java): implement SettlementResponse class

81f6f99

Signed-off-by: Stefano Amorelli <stefano@amorelli.tech>

feat(java): implement VerificationResponse class

4fcabe1

Signed-off-by: Stefano Amorelli <stefano@amorelli.tech>

feat(java): implement facilitator client

98233ab

Signed-off-by: Stefano Amorelli <stefano@amorelli.tech>

feat(java): implement X402HttpClient

4fd6ac0

Signed-off-by: Stefano Amorelli <stefano@amorelli.tech>

feat(java): implement PaymentFilter

2f82f19

Signed-off-by: Stefano Amorelli <stefano@amorelli.tech>

test(java): add integration test

6415990

Signed-off-by: Stefano Amorelli <stefano@amorelli.tech>

feat(java): expand exception handling in paymentfilter

7a1cfd2

chore(java): improve javadocs

29399ca

doc(java): add README.md

b59dc91

Signed-off-by: Stefano Amorelli <stefano@amorelli.tech>

refactor(crypto): introduce protocol-specific signing rules for Crypt…

00f7962

…oSigner

ci(java): setup java ci with maven and tests

80b31aa

stefanoamorelli force-pushed the feat/java branch from fd0ca9a to 80b31aa Compare May 28, 2025 20:09

erikreppel-cb approved these changes May 29, 2025

View reviewed changes

erikreppel-cb approved these changes Jun 2, 2025

View reviewed changes

erikreppel-cb merged commit add0b93 into coinbase:main Jun 2, 2025
10 of 11 checks passed

+<module name="JavadocPackage"/> <module name="MissingJavadocType"> <property name="scope" value="public"/> <property name="excludeScope" value="package"/> </module>
+    <module name="MissingJavadocMethod"> <property name="scope" value="public"/>
+      <property name="excludeScope" value="package"/>
+      <property name="allowMissingPropertyJavadoc" value="true"/> </module>
+    <module name="MissingJavadocVariable"> <property name="scope" value="public"/>
+    </module>
+    <module name="JavadocStyle"> <property name="checkFirstSentence" value="true"/>
+      <property name="endOfSentenceFormat" value="([.?!][ \t\n\r\f<])|([.?!]$)"/>
+      <property name="checkEmptyJavadoc" value="true"/>
+      <property name="checkHtml" value="true"/>
+    </module>

[Feat] Java implementation #178

[Feat] Java implementation #178

Uh oh!

Conversation

stefanoamorelli commented May 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel bot commented May 15, 2025

Uh oh!

cb-heimdall commented May 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Heimdall Review Status

Uh oh!

erikreppel-cb commented May 15, 2025

Uh oh!

stefanoamorelli commented May 16, 2025

Uh oh!

erikreppel-cb commented May 26, 2025

Uh oh!

stefanoamorelli commented May 26, 2025

Uh oh!

erikreppel-cb commented May 27, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

erikreppel-cb commented May 28, 2025

Uh oh!

stefanoamorelli commented May 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stefanoamorelli commented Jun 2, 2025

Uh oh!

Uh oh!

erikreppel-cb commented Jun 2, 2025

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

4 participants

stefanoamorelli commented May 15, 2025 •

edited

Loading

cb-heimdall commented May 15, 2025 •

edited

Loading

stefanoamorelli commented May 28, 2025 •

edited

Loading