Skip to content
SineraDocs

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

LayerStatus
Byte layouts, addresses, hashes, instruction encodings and fee arithmeticChecked against vectors produced by the Rust program
SDK with a mocked connectionPasses in continuous integration
SDK transactions on the compiled program, local validator, real RPCRun, covering creation, settlement and award flows
Rollback of a local validator ledgerReorg, stale block and unknown-outcome errors reported
Devnet, mainnet, multi-validator clusters, wallet adaptersNot 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:package

Then 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.

FieldWhat it pins
genesisHashThe cluster
programIdThe program
programData.executableSha256The build
programData.upgradeAuthorityWho may upgrade, or null for an immutable program
domainThe signing domain every package binds
sinMintThe SIN mint recorded in the registry
configIdThe 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 mismatch

Construction makes no network call. read.verify() throws on any mismatch.

Client calls

CallPurpose
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:

CodeMeaning
CHAIN_MISMATCHThe cluster genesis hash differs from the deployment
DEPLOYMENT_MISMATCHProgram, upgrade authority, registry or config does not match
NOT_FOUNDA required account is absent at the observed slot
REORGThe observed slot no longer carries the same block hash
STALE_BLOCKThe observation is too old or the blockhash expired
PROTOCOL_REVERTThe program failed. details.error holds the decoded error
PACKET_TOO_LARGEThe transaction exceeds 1,232 bytes
USER_REJECTEDThe signer declined
OUTCOME_UNKNOWNThe broadcast or confirmation outcome is unknown. details.signature is set

On OUTCOME_UNKNOWN, reconcile with the signature. Do not retry blindly.