This file describes the toolkit's experimental local signer and unsigned delegation builder, their Solana evidence model, and dependency boundaries. These are implementation contracts, not new exchange features.
TL;DR
- The evaluated dependency surface is Rise 0.5.28 with
@solana/kit4.0.0; pin and test exact versions. - The TypeScript core uses exact strings/bigints; the signer receives ticks and lots directly.
- One intent produces at most one signature. Retrying the same signed bytes is different from signing a new transaction.
- Unknown remains unknown until chain evidence resolves it.
- Signer endpoints, compute policy, fee policy, timing, and caps require explicit configuration.
1. SDK and package boundaries
@ellipsis-labs/rise is the official Phoenix perpetuals SDK. Its builders produce instructions rather than completing the signing/submission workflow. The evaluated version is ESM; its package metadata and peer requirements should be checked in the lockfile. Retain the ws peer required by @solana/kit instead of omitting peers during installation.
Pass public deployment accounts explicitly rather than rely on SDK ambient environment selection. The stable TypeScript core is separate from the experimental signer/delegation entry points. The latter carry external dependencies and require fresh operational validation before fund-bearing use.
2. Intent and HTTP contract
An intent contains an ID and an exact request body. Reusing the ID with the same body returns the same known outcome; a different body conflicts. The signer validates, persists signed work, sends it, and tracks one signature. The caller supplies the client-order hash namespace; it is not a private or hidden default.
Result states are confirmed, failed, and unknown, with signature and slot evidence where available. An unsigned unknown guarantees the signer will not later sign that request. A signed unknown can still land and must be resolved through its signature.
Validation/authentication/conflict/oversize refusals occur before signing. A forgotten finalized intent can return its retained signature through the tombstone contract. Endpoint status codes and exact payload fields are documented by the shipped client and signer; do not infer successful trade execution from HTTP 200.
The signer persists an intent before sending signed bytes. Restart restores unresolved signed intents. Only final outcomes become eligible for configured forgetting; tombstones prevent a previously used ID becoming a fresh order. An unresolved journal entry must not be discarded because a client timeout expired.
3. Solana submission and resolution
Build a versioned transaction with explicit compute-limit and priority-price instructions followed by the Phoenix instruction. Measure final byte size before signing. The position-authority key is the fee payer in the ordinary experimental trade signer workflow.
Rebroadcast only the same serialized signed transaction while its blockhash remains usable. Never refresh the blockhash by re-signing the same logical intent: the earlier transaction may still land, creating a second execution.
Status polling and transaction parsing supply confirmation/failure evidence. getTransaction without usable metadata is still “not found yet.” Expiry resolution must combine blockheight beyond the last-valid boundary with repeated absent signature-status evidence; different RPC replicas can disagree. Poll intervals and safety margins remain caller configuration.
The IoC's separate last-valid-slot window prevents a late transaction from filling after the chosen slot boundary. It does not prevent the transaction paying a fee. Pending memory in orders.md §6 must account for the physical window and later reads.
4. Local security and resource policy
The sidecar is intended for loopback, uses fail-closed bearer authentication, rejects browser-origin requests, and never exposes key material in health or logs. Read credentials through caller-selected local secret storage. Mask authenticated RPC URLs as well as explicit secret fields.
Compute limits, priority-fee percentile/clamps, signing deadline, maximum inflight work, SOL alert floor, notional cap, and collateral multiplier are application policy. Require them where the interface needs them; do not carry values selected for a particular workload as universal defaults.
An optional notional cap uses exact quote lots. Unknown collateral blocks an ordinary exposure-increasing operation requiring that cap evidence; it must not be replaced with a fabricated zero or a stale favorable value. The caller chooses the separate handling of cancellations and reducible writes.
Header reads can be shared through a single source with explicit maximum age. Use the RPC account-info context slot rather than separately fetched head slot to describe those bytes. A stale fee-payer balance is unknown, not current spendable SOL.
5. Delegation builder
The experimental builder constructs an owner-signable DelegateTrader transaction from caller-supplied authority/PDA/delegate identity and validated raw header. Simulation with signature verification disabled checks the unsigned structure; it does not grant access or establish acceptance of the final signed transaction.
No onboarding web page, wallet account, local configuration containing user identities, or automatic delegation submission is packaged with this workflow. The header/binding model is in account-and-delegation.md §3.
Pitfalls
| What breaks | Why | Correct approach |
|---|---|---|
| Timeout retry doubles execution | A new blockhash produced a new signature | Track/rebroadcast one signature |
| Startup silently forgets unresolved work | Journal treated as transient cache | Retain unresolved intents |
| Confirmed HTTP result called filled | Chain success is not program fill | Parse return data and slot-qualified account change |
| Peer module missing | Installation dropped peer dependencies | Lock and test the full signer dependency set |
| Simulation called approval | Unsigned structure is only a check | Separate build, authorization, and submission |
Open questions / not verified
- The packaged experimental signer requires live validation after dependency or deployment changes.
- Priority-fee and CU requirements under complex accounts and large batches.
- RPC provider quotas, worst-case replica disagreement, and unsigned delegation acceptance beyond offline/simulation checks.
Sources
Rise public source; Rise SDK; Orders; Transactions; getSignatureStatuses; getTransaction. Evaluated SDK version: 0.5.28. One-signature journals, tombstones, local authentication, and caps are experimental toolkit contracts.
© markpaper authors. Licensed under CC BY 4.0: when publishing or adapting this material, credit “markpaper — Phoenix knowledge base” and link to the original and the license.