SDK reference
Main classes, functions, data types and hashing helpers of the ATP TypeScript SDK candidate.
This page summarises the public surface of the ATP TypeScript SDK 0.1.0 candidate, targeting ATP 2.4.0. The package exports exact TypeScript signatures. This page names the main entries and what they do. For installation see the SDK overview.
Implementation candidate
Client construction
createAtpClient({ publicClient, deployment }) returns a frozen client bound to a cloned copy of your deployment. Construction and module import make no RPC request, signing, approval or submission. Standalone functions with the same names accept publicClient and deployment explicitly.
| Method | Purpose |
|---|---|
read.verify(options?) | Verify the selected runtime and config bindings. Returns the config and an observation |
read.atom(locator, options?) | Read Core state and the receipt projection with provenance |
read.view(module, method, args, options?) | A verified, typed view getter |
read.decisionData(atomId, package, route?) | Case-bound payload, digest and decision preflight. Omit the route for an award |
read.bindExecutor(address) | Verify clone, factory and session bindings. Returns a clone-bound context |
prepare.call(module, method, args, account) | Encode an allowlisted public action |
prepare.creation(input, payer, session?) | Validate the creation context. Returns the call, a separate approval, typed data, fee and predicted Atom id |
prepare.approval(token, spender, amount, owner) | Prepare an explicit approval to the pinned vault |
prepare.session(terms, root, now) | Validate terms and prepare root session creation |
prepare.receiptClaim(locator, payer) | Prepare a post-final receipt claim |
prepare.feeClaim(locator, kind, payer) | Prepare payment of an unpaid fee obligation to its fixed recipient |
prepare.metadata(locator, publisher, revision, input) | Validate finalized root publication |
simulate(call) | Read-only canonical preflight with the actual caller |
write(simulation, wallet) | Submit after a fresh preflight and wallet checks |
waitAndReadback(submitted, options?) | Reconcile receipt, payload, canonical block, events and Core state |
Data types
| Type | Meaning |
|---|---|
Deployment | bigint chain id and deployment block, bytes32 config id and module bindings. Core and registry are required |
RuntimeBinding | Address and runtime hash of the complete deployed bytes |
AtomLocator | Chain id, exact Core address and bytes32 Atom id |
ReadOptions | Optional finalized, safe or latest block tag, explicit block number, and maxAgeSeconds |
Observation | Chain id, block number and hash, timestamp, finality and observation time |
CreationInput | Intent, time policy, asset policy, resolution policy and the signatures or root proofs the route needs |
PreparedCall | Module, function, args, chain, config, target, account, calldata and zero native value |
Simulation | A prepared call with its decoded preflight result and observation |
Submitted | Submission status, transaction hash and the prepared call |
BoundExecutor | Clone-bound deployment with executor, root, operator, token, session and active flag |
Amounts, salts and wide integer fields use bigint. Use stringifyWire for JSON transport and structFromWire to rebuild validated structs.
read.atom returns state, outcome, config id, completion mode, receipt and observation. Its deadlines object reports unavailable, because Core has no full deadline getter. A provider failure throws. It never becomes "not found".
Public action allowlist
prepare.call encodes only public actions:
| Module | Actions |
|---|---|
AtomCore | createAndEscrow, acceptOriginal, proposeRevision, acceptRevision, cancelPending, confirmCompletion, openDispute, executeTimeout |
AtomCore session variants | createAndEscrowWithSession, acceptOriginalWithSession, proposeRevisionWithSession, acceptRevisionWithSession, confirmCompletionWithSession |
AtomCore dispute finalizers | finalizeDisputeByConsensus, finalizeDisputeByAward |
DelegationManager | createSession, revokeSession, revokeAll |
SessionExecutorFactory | createExecutor |
The allowlist excludes governance and admin changes, direct module calls and vault shortcuts. Deadline, authorization and state checks stay with the contracts. Listing an action does not let an arbitrary caller act in a role it does not hold.
Hashing and typed data
| Helper | Result |
|---|---|
hashStruct(name, model) | Canonical struct hash with exact field order and widths |
typedData(name, model, context) | EIP-712 payload for the chain and contract you pass |
intentDigest(intent, chainId, atomCore) | Intent digest in the Core domain |
atomId(chainId, core, rootBuyer, salt) | Atom identity, independent of any global sequence |
atomKey(chainId, core, atomId) | Cross-deployment Atom key |
configId(chainId, core, modules) | Config commitment for the module set |
assetId(chainId, registry, seller, objectRef) | Seller-namespaced inventory id |
hashTerms(terms) | Hash of all delegation terms |
sessionId(chainId, manager, terms, epoch, nonce) | Predicted session id |
executorSalt(root, operator, token, userSalt) | Deterministic executor salt |
predictExecutor(factory, implementation, salt) | Predicted executor clone address |
encodeAwardProof(pair) / decodeAwardProof(bytes) | Exactly two distinct signer and signature entries |
Design boundaries
| Layer | Responsibility |
|---|---|
| Hashing and signing | Offline functions that authorize and submit nothing |
| Read and verification | Needs no signer. A failed read is never reported as absence |
| Preparation | Typed allowlist and explicit previews |
| Simulation and write | Checks the actual caller and context. A simulation cannot promise a future mined result |
| Reconciliation | Inclusion and protocol finality stay separate concepts |
The Atom id binds chain, Core, root buyer and salt. Never use an application order id in its place. Intent typed data uses the Core as verifying contract. Root eligibility and dispute typed data use the arbitration case manager. A new Atom must also use a fee snapshot the deployment admits.
The contracts remain the authority. The SDK checks inputs early, but it does not replace on-chain rules. For the portal view of the same operations see Create an Atom.