Solana SDK (candidate)
The ATP Solana TypeScript SDK candidate, its status, its client calls and the errors it reports.
The ATP Solana SDK is a TypeScript client for the Solana implementation of ATP 2.4.0. It follows the same explicit flow as the EVM SDK: read, prepare, simulate, write, read back.
Implementation candidate
No public deployment
The Solana program is not deployed, has had no external audit and has no production approval. The SDK has run against the compiled program only on a local validator. It has not run on devnet, mainnet or any public cluster. The package is @sinera/atp-solana-sdk 0.1.0 and is not published to a package registry.
What has been run
| Layer | Status |
|---|---|
| Byte layouts, addresses, hashes, instruction encodings and fee arithmetic | Checked against vectors produced by the Rust program |
| SDK with a mocked connection | Passes in continuous integration |
| SDK transactions on the compiled program, local validator, real RPC | Run, covering creation, settlement and award flows |
| Rollback of a local validator ledger | Reorg, stale block and unknown-outcome errors reported |
| Devnet, mainnet, multi-validator clusters, wallet adapters | Not verified |
Install
Build from the repository. You need Node 20 or newer and npm.
cd sdk/typescript
npm ci
npm run verify
npm run check:packageThen install the tarball with its peer dependency in your project:
npm install /path/to/sinera-atp-solana-sdk-0.1.0.tgz @solana/web3.js@1.98.4@solana/web3.js 1.98.x is a peer dependency. The SDK uses legacy transactions and classic SPL Token only. It does not use the Anchor runtime.
Select a deployment
A Deployment is trusted input. Nothing is defaulted or discovered. Take every value from a reviewed deployment record.
| Field | What it pins |
|---|---|
genesisHash | The cluster |
programId | The program |
programData.executableSha256 | The build |
programData.upgradeAuthority | Who may upgrade, or null for an immutable program |
domain | The signing domain every package binds |
sinMint | The SIN mint recorded in the registry |
configId | The config |
SIN is a planned token and has not been issued. Any mint in a deployment record here is for testing only.
import { createAtpSolanaClient } from '@sinera/atp-solana-sdk';
const atp = createAtpSolanaClient({ connection, deployment });
const verified = await atp.read.verify(); // throws AtpError on any mismatchConstruction makes no network call. read.verify() throws on any mismatch.
Client calls
| Call | Purpose |
|---|---|
read.verify(o?) | Verify the deployment against the cluster |
read.atom(locator, o?) | Atom account, state, vault, timing and observation |
read.config(o?) / read.registry(o?) | Config and registry |
read.session(root, nonce, o?) | Delegation session and its vault |
read.feeClaims(locator, o?) | Fee legs and recipients |
prepare.* | Build an unsigned transaction for one of 29 public instruction families |
simulate(prepared) | Simulate the exact unsigned message |
write(simulation, signers) | Sign with signers you supply, then broadcast |
waitAndReadback(submitted) | Confirm, decode events and read the Atom back |
predictAtom(buyer, salt) | Predicted Atom and vault addresses |
Every read pins one block and re-checks its hash. The default commitment is finalized. The SDK never signs for you. write takes the signers you pass in. It sends with no automatic retries.
Fees
quoteSettlement(amount, decision, route, fee) reproduces the program's settlement arithmetic in integers and returns buyerOut, sellerOut, companyFee, ecosystemFee and heldDisputeFee.
Errors
Errors are AtpError instances with a code:
| Code | Meaning |
|---|---|
CHAIN_MISMATCH | The cluster genesis hash differs from the deployment |
DEPLOYMENT_MISMATCH | Program, upgrade authority, registry or config does not match |
NOT_FOUND | A required account is absent at the observed slot |
REORG | The observed slot no longer carries the same block hash |
STALE_BLOCK | The observation is too old or the blockhash expired |
PROTOCOL_REVERT | The program failed. details.error holds the decoded error |
PACKET_TOO_LARGE | The transaction exceeds 1,232 bytes |
USER_REJECTED | The signer declined |
OUTCOME_UNKNOWN | The broadcast or confirmation outcome is unknown. details.signature is set |
On OUTCOME_UNKNOWN, reconcile with the signature. Do not retry blindly.