Developer Experience Improvements - Feedback from Real-World Usage

[paulgnz]

Developer Experience Improvements

Feedback and suggestions based on real-world development experience building Proton.Link and related dApps.

---

1. Better Error Messages for Failed Transactions (High Priority)

Issue: When transactions fail, error messages are sometimes technical/cryptic and not helpful for end users.

Current behavior:

"assertion failure with message: insufficient balance"

Suggestion: Wrap common errors with user-friendly messages:

{
  code: "INSUFFICIENT_BALANCE",
  message: "You don't have enough XPR to complete this transaction",
  technical: "assertion failure with message: insufficient balance",
  suggestion: "Current balance: 10.0000 XPR, Required: 50.0000 XPR"
}

This would help dApp developers show better error messages without having to parse error strings manually.

---

2. Built-in Retry Logic for RPC Failures (Medium Priority)

Issue: RPC endpoints occasionally fail or timeout, requiring manual retry logic in every dApp.

Suggestion: Add configurable retry with fallback endpoints:

const proton = new ProtonWebSDK({
  endpoints: ['https://proton.eosusa.io', 'https://proton.greymass.com'],
  retryConfig: {
    maxRetries: 3,
    retryDelay: 1000,
    fallbackOnFailure: true
  }
});

---

3. TypeScript Types for Table Rows (Medium Priority)

Issue: get_table_rows returns any type, requiring manual typing in TypeScript projects.

Suggestion: Add generic type support:

interface Rating {
  account: string;
  level: number;
  reason: string;
}

const { rows } = await rpc.get_table_rows<Rating>({
  code: 'protonrating',
  table: 'ratings',
  // ...
});
// rows is now Rating[] instead of any[]

---

4. Session Persistence Helpers (Low Priority)

Issue: Session restoration requires boilerplate code in every dApp.

Current pattern we use:

// On app load
const { user, error } = await ProtonSDK.restoreSession();
if (!error && user?.actor) {
  setAuth(user.actor);
  setAccountData(user);
}

Suggestion: Add built-in persistence option:

const proton = new ProtonWebSDK({
  persistSession: true,  // Auto-save to localStorage
  sessionKey: 'proton_session',  // Custom key
  onSessionRestore: (user) => console.log('Welcome back', user.actor)
});

---

5. Transaction Status Tracking (Low Priority)

Suggestion: Add transaction status checking for apps that need to verify irreversibility:

const result = await proton.transact(actions);

// Check if transaction is irreversible
const status = await proton.getTransactionStatus(result.transactionId);
// { status: 'irreversible', block: 12345, confirmations: 330 }

---

6. Pagination Helper for Large Tables (Medium Priority)

Issue: Fetching all rows from large tables requires manual pagination.

Current pattern:

let lower_bound = '';
while (true) {
  const { rows, more } = await rpc.get_table_rows({ lower_bound, ... });
  // process rows
  if (!more) break;
  lower_bound = rows[rows.length - 1].id;
}

Suggestion: Add async iterator:

for await (const row of rpc.iterateTable('contract', 'table')) {
  // process each row, pagination handled automatically
}

---

Summary

Suggestion	Priority	Impact
Better error messages	High	Improves end-user UX
TypeScript generics for tables	Medium	Better developer experience
Built-in retry logic	Medium	More resilient dApps
Table pagination helper	Medium	Cleaner code
Session persistence	Low	Reduces boilerplate
Transaction status tracking	Low	Nice for specific use cases

Happy to discuss any of these further or contribute PRs if there's interest!

[paulgnz]

Updates based on feedback

Point 3 - TypeScript Types for Table Rows

Update: @rockerone/abi2ts already exists and solves this:

# Generate types from contract on mainnet
npx abi2ts protonrating > ./types/protonrating.ts

# From local ABI file
npx abi2ts mycontract -f ./target/mycontract.abi > ./types/mycontract.ts

This might be better suited as a @proton/cli feature rather than SDK:

proton contract:generate-types protonrating ./src/interfaces
# or integrated with deployment:
proton contract:set mycontract ./target --generate-types ./src/types

Point 4 - Session Persistence Helpers

Update: Removing this suggestion - the SDK already has a restore flag for session management. The existing implementation covers this use case.

---

Revised priority:

Suggestion	Priority	Notes
Better error messages	High	Still relevant
Built-in retry logic	Medium	Still relevant
TypeScript generics	Low	Solved by @rockerone/abi2ts, better as CLI feature
Table pagination helper	Medium	Still relevant
Transaction status tracking	Low	Still relevant

[andreyjamer]

@paulgnz For this issue Better error messages. This error message comes from server side response of RPC endpoint for transaction push. UI just forwards this error.

Actually this response has much more data then just a string:

This data can be reached through error object thrown by the transact method.
For example:

try {
    return await session.transact(...)
} catch (error) {
    console.log('Error details', error.json)
}

error.json object contains the response body of the error. As you can see on the screenshot this response already contains the error code.

There are some errors related to this:

1. Error code is internal I guess. I don't remember if we expose error codes on any package
2. The error details are still not use friendly and lacks info you requested. Like current and required balances. I'm not sure if it will be possible to add.

Anyway I created an internal ticket to review this with the backend team.

[andreyjamer]

@paulgnz Could you provide more info about this issue Built-in retry logic? Is it about the actual transaction push?

[andreyjamer]

@paulgnz I'm not fully understand this issue Pagination Helper for Large Tables.
RPC method get_table_rows designed to return rows from table with or without a filtration. It is quite generic. So it return fetched rows and marker more that identifies if more rows are available. + it returns next_key and next_key_bytes that could be used to fetch further rows.

So it could be used for different case:

1. We need to fetch all rows with one function call. This is what is mentioned in your example.
2. We need to fetch some rows and fetch others rows only if user uses the pagination component in UI

These cases depends on the application logic, so I'm not sure if the need to extend the generic API with such a specific methods like rpc.iterateTable('contract', 'table'). May be we can introduce a method like get_table_rows_all with the same signature as get_table_rows. It will allow to use all filtration issues + introduce a generic tool to get all rows with one function call.
But I'm not sure if it will cover all your cases.

What I'm also not use it this for await (const row of rpc.iterateTable('contract', 'table')) { Here we iterate through each row. It means we need to fetch each row at a time. Shouldn't it be something like:

for await (const rows of rpc.get_table_rows_all({...})) {
    for (const row of rows) {
       // each row processing
    }
}

[andreyjamer]

I added support for generic types for Table Rows. New package version of @proton/js will be released soon.

[paulgnz]

Thanks for the detailed responses @andreyjamer!

Re: Better Error Messages

That's helpful - I wasn't aware of error.json containing the full response. The screenshot shows exactly what I was looking for. We'll update our error handling to use:

try {
    return await session.transact(...)
} catch (error) {
    const details = error.json?.error?.details?.[0]?.message;
    // "assertion failure with message: overdrawn balance"
}

A documented list of common error codes (3050003, etc.) and their meanings would be useful for developers, but the existing data is workable.

Re: Built-in Retry Logic

This is about RPC endpoint failures, not transaction retries. Sometimes an endpoint returns 502/503 or times out, requiring a fallback to another endpoint. Currently we handle this manually:

const endpoints = ['https://proton.eosusa.io', 'https://proton.greymass.com'];
// Manual retry logic with endpoint rotation

Would be nice to have this built into the SDK initialization, but it's a "nice to have" not critical.

Re: Pagination Helper

Your suggestion of get_table_rows_all with the same signature makes more sense - it keeps the API consistent. My async iterator example was more pseudocode showing the desired outcome (not fetching row-by-row). Your approach would work well:

const allRows = await rpc.get_table_rows_all({
    code: 'contract',
    scope: 'contract', 
    table: 'mytable',
    limit: 100  // batch size per request
});

Re: Generic Types

Excellent news on the generic types support in @proton/js! 🎉

[andreyjamer]

@paulgnz I implemented get_table_rows_all method. I mentioned you in the PR for @proton/js package and in the ticket.

[SuperstrongBE]

@andreyjamer can the RPC get_table_rows_all and get_table_rows could have a generic type like 'get_table_rows_all' to allow rows type ?

[andreyjamer]

@SuperstrongBE It already has. The signature is the following

get_table_rows_all<T = any>(...) :T[] 

This method is a wrapper for get_table_row, so T is passed there.
In the end the function will return the array, not an object as get_table_rows.

[andreyjamer]

@SuperstrongBE unfortunatelly a new version of proton/js is not yet released, so you cannot try it.

[andreyjamer]

@SuperstrongBE @paulgnz Hello! We just released new versions of @proton/api and @proton/js. Feel free to try it to get support for generics

[andreyjamer]

@paulgnz Returning to this request Built-in Retry Logic.

Issue: RPC endpoints occasionally fail or timeout, requiring manual retry logic in every dApp.

Suggestion: Add configurable retry with fallback endpoints:

const proton = new ProtonWebSDK({
  endpoints: ['https://proton.eosusa.io', 'https://proton.greymass.com'],
  retryConfig: {
    maxRetries: 3,
    retryDelay: 1000,
    fallbackOnFailure: true
  }
});

This is about RPC endpoint failures, not transaction retries. Sometimes an endpoint returns 502/503 or times out, requiring a fallback to another endpoint. Currently we handle this manually.

I checked the implementation and actually we already have a built-in mechanism of retry. endpoints parameter is passed to the internal JsonRpc object. For example we have following array of endpoints:

[
"https://rpc.api.testnet.metalx.com",
"https://proton-testnet.eoscafeblock.com",
"https://test.proton.eosusa.io",
]

The first value is used by default. If this endpoint is not available for some reason, then we move it to the end of the list and take first one from the list. So all endpoints are rotated until the request is sent or we reached the size of the list.

And returning back to your request, I'd like to understand what is the purpose of the retryConfig.

1. Is your idea is that we keep the current mechanism but improve it?
2. Should we do maxRetries for each endpoint before taking the next one?
3. And then retryDelay should be used for delay between attempts, right?
4. fallbackOnFailure is completely unclear for me now. What is it for?

I'd like to clarify all these points and then I can try to do the best implementation.

BTW we have timeout for each request to RPC endpoint that is 5000 ms by default. Right now it is not configurable through ProtonWebSDK object.