Repository navigation
docs: add API contract between Flutter app and Serverpod - #77
Merged
Merged
Conversation
TOMOKI977
added
area: architecture
TOMOKI977
requested review from
Pericena,
XxHugheadxX,
fercodes and
moises-cisneros
October 2, 2026 06:02
Deploying puls3 with
|
| Latest commit: |
88ffebd
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://5496b698.puls3-4lw.pages.dev |
| Branch Preview URL: | https://docs-8-api-contract.puls3-4lw.pages.dev |
Define the Serverpod endpoints, models, errors, relay and polling rules for the MVP flows, aligned with the ERC-8183 escrow and hire states from ADR-0005. Refs #8
Remove the server-signed setBudget step, since create_job carries token and budget. Add the approval window and the permissionless release call, restrict claim_refund to Funded, document fund parameters and the fee snapshot, and reference is_expired.
TOMOKI977
force-pushed
the
docs/8-api-contract
branch
from
October 5, 2026 19:00
c118bc4 to
88ffebd
Compare
This was referenced Oct 5, 2026
TOMOKI977
requested review from
Pericena,
XxHugheadxX,
anahillanos474-max,
fercodes and
moises-cisneros
and removed request for
Pericena,
XxHugheadxX,
fercodes and
moises-cisneros
October 5, 2026 19:46
Contributor
Author
|
@moises-cisneros @XxHugheadxX @Pericena @fercodes @anahillanos474-max este PR es el que destraba el camino crítico de Stellar Elite (plan en #51): es la referencia para el relay de hire y pago (#96, #97) y para reconvertir #93. Ya está rebaseado sobre |
moises-cisneros
approved these changes
Oct 5, 2026
This was referenced Oct 5, 2026
4 tasks done
This was referenced Oct 7, 2026
Closed
5 tasks done
Pericena
added a commit
that referenced
this pull request
Oct 8, 2026
Part B of the #109 split. Refs #27: the testnet end-to-end criterion waits for the deploy endpoint (#18) and the relay (#96). - DeployFlow + DeployFlowController: preparing -> waiting for signature -> registering on-chain -> activating -> live. Never runs twice, resumes from the failed step, keeps the prepared and signed transaction across a lost response, verifies every backend answer, and stops if the flow is closed mid-run. - Presentational widgets: DeployStepper, phase card, error panel and success, with skeletons until values arrive. - Errors with a recovery action and no reload: signature rejected, transaction failed, backend error, plus wallet unavailable, wrong network, account changed, connection lost/timeout, invalid response, expired preparation (prepares again) and a wallet that never answers (times out; the sheet can be closed while the wallet prompt is open). Review fixes: - The demo gateway is labelled: a banner says nothing is registered on Stellar, and the result reads "Demo deploy only" with no explorer link, no agent page and no made-up hash. Demo agents are not listed. - WalletPort.signTransaction only signs and returns the signed XDR; the server submits (API contract #77, Decision A). MockWallet returns a marked signed placeholder instead of a hash. - Real agents start at a 0.0 rating; explorer links use stellarExpertTxUrl; the unused SuccessPanel, DeployProgressView and AppScope.ids are removed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This was referenced Oct 8, 2026
5 of 7 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #8
Summary
Adds the contract between the Flutter app and Serverpod:
docs/architecture/api.md: endpoints, errors, relay and polling rules, response shapes, and the traceability from every MVP flow step (docs: MVP user flows #22) to an endpoint or client-only action.docs/architecture/models/*.spy.yaml: draft Serverpod models (agent, hire, payment, feedback, skill, prepared transaction, chain submission, API exception).Key decisions
create_job(carrying token and budget), thenfund. A Soroban transaction holds one contract invocation, so they cannot be combined without a non-standard call.complete) or rejects (reject) as evaluator, and can reject a submitted job only beforeapproval_deadline. The agent'ssubmitand the permissionlessreleaseandclaim_refundare server-submitted.open → funded → submitted → completed / rejected / expired.create_jobconfirms.expired_atis derived asexpired.runtimeStatus,rejectedFromandfeedbackReferenceare data, not states.claim_refundafterexpired_at.expired_at. Timeout values come from config (ADR-0005 D3, deferred).Acceptance criteria
puls3_domaincatches up in feat: align Hire lifecycle with ERC-8183 #73Depends on / follow-ups
create_job,fund,submit,complete,release,reject,claim_refund,is_expiredClaimableTTL, evaluator must not be the provider)give_feedbackarguments, docs: update MVP flows to ADR-0005 escrow and hire states #76 flows copy