DEVELOPER REFERENCE · PROTOCOL SPEC

From device to onchain wallet.

Comprehensive developer guides for hardware roboticists, smart contract engineers, and fleet operators. Official SDK libraries available in TypeScript, Python, and ROS2.

Client SDKs

Integrate in three lines of code.

The target design signs inside a hardware secure element so keys never leave the device. That support is planned: the SDK key stores are software today. Gas is sponsored by the PINELY Paymaster.

// 1. Install the SDK
bun add @pinely/sdk

// 2. Connect. The development key store is for testing only: never use it in production.
import { Pinely } from "@pinely/sdk";

const pinely = await Pinely.connect({
  chain: "elysiumTestnet", // chain 99801
  registryAddress: "0x...", // MachineRegistry, from the address book
  paymasterAddress: "0x...", // PinelyPaymaster
  keyStore: { type: "file-dev-only", privateKey: "0x..." },
  rpcUrl: process.env.RPC_URL_ELYSIUM_TESTNET,
});
const machine = await pinely.machines.create({ name: "charger-01", operator: "0x..." });

// 3. Pay a charging dock over HTTP 402. The SDK reads the dock's 402 challenge, has the
//    Facilitator prepare a gas-sponsored UserOperation, checks it, signs it and submits it.
const result = await machine.pay({
  url: "https://facilitator.example/v1/charge/dock-001",
  maxAmount: 100_000n, // 0.10 USDC (6 decimals): the most this machine will pay
  facilitatorUrl: "https://facilitator.example",
});

// "settled" only after the Facilitator confirms the payment onchain.
console.log(result.status, result.txHash);

// Command line equivalent:
// pinely pay --url https://facilitator.example/v1/charge/dock-001 \
//   --max-amount 100000 --facilitator https://facilitator.example
Protocol Architecture

The Four-Stage Execution Pipeline

How an autonomous physical device triggers a transaction on a public street and settles on Elysium without custody risk.

Step 1

Device signing

The device builds an EIP-712 spend intent and signs it with its session key. The goal is to hold that key in a secure element such as the NXP SE050 or a TPM 2.0 so it cannot be exported; today the SDK signs with a software key store.

Step 2

UserOp Dispatch

The intent becomes an ERC-4337 UserOperation. The machine signs its hash with its session key and submits it to a bundler.

Step 3

PinelyPaymaster

Paymaster checks the account's prepaid USDC credit, advances native HYPE gas for EVM execution, and bills it in canonical USDC.

Step 4

PinelyHook (Uniswap v4, Stage 2)

Hook evaluates 4 immutable guards (Machine Gate, Spend Policy, Kill Switch, and Tier Fee Cooling). Any violation reverts onchain fail-closed.

PINELY Facilitator

How a machine pays over HTTP 402.

The Facilitator lets a charging dock, an API or a data provider get paid in USDC by a machine, using the x402 pattern. It prepares and confirms the payment; it never holds the machine's key.

Step 1

The service answers HTTP 402

The machine asks a charging dock, API or data provider for a resource. The provider answers HTTP 402 with the payment requirements: the amount, USDC, the address to pay and the network.

Step 2

The machine signs what it will pay

The machine signs an EIP-712 Payment402Intent: machine ID, resource, amount, a one-time nonce and a deadline. The signing domain is PINELYFacilitator, bound to the chain ID.

Step 3

The Facilitator checks and prepares

It checks the signature against the session key registered in MachineRegistry, rejects an expired or reused intent and a frozen machine or fleet, then returns an unsigned, gas-sponsored UserOperation.

Step 4

The machine verifies before it signs

The SDK checks the UserOperation field by field and refuses one that pays another recipient or token, a larger amount, another Paymaster or inflated gas. Only then does it sign and submit.

Step 5

Confirmation unlocks access

The Facilitator returns an access token only after the payment is confirmed onchain. The provider receives the amount minus the Facilitator fee.

What you can rely on

  • Rail: ERC-4337 with the PINELY Paymaster. The machine needs no HYPE for gas.
  • Fee: 0.1% of each payment (10 basis points by default), taken only when a fee recipient is configured. The SDK refuses a fee above its limit, 1% by default.
  • Never simulated: without a Facilitator URL the SDK returns a failed result, never a made-up success.
  • Replay protection: every intent carries a one-time nonce and a deadline; a reused nonce is rejected.
  • Spend limits: enforced onchain by the Stage 2 PinelyHook Spend Policy, not by the Facilitator.

Facilitator endpoints

EndpointPurpose
GET /v1/charge/:idReference HTTP 402 challenge for a charging request
GET /v1/capabilityReports the settlement rail
POST /v1/verifyVerifies a signed payment intent before payment
POST /v1/settle/prepareReturns the unsigned, gas-sponsored UserOperation
POST /v1/settleSubmits the signed UserOperation and returns the access token after confirmation
Contract Address Book

Official SSOT Contract Registry

Official deployment addresses synchronized from Foundry compilation artifacts across Elysium Testnet (99801) and Mainnet (99901).

Contract NameFunctional ScopeRollout StageOnchain Address (SSOT)Action
MachineRegistryHardware chip registry & onchain status trackerStage 10xbf1f9ea8...547fbc07
PinelyAccountFactoryERC-4337 factory with CREATE2 deterministic salt (PINELY_ACCOUNT_V1)Stage 10xdab0099e...7ce18227
PinelyPaymasterNative HYPE gas sponsor & canonical USDC settlement with bounded ratesStage 10x9960a800...e5aea936
SurplusSweeperAutomated machine surplus keeper & Safe treasury sweeperStage 10xb1f5c1d5...b1fcd2ba
Canonical USDCElysium official 6-decimal bridged settlement stablecoinOfficial0x7D29d804...edcB47b2
Wrapped HYPE (WHYPE)Canonical ERC-20 wrapped native gas tokenOfficial0xCD57F65c...46E1F234
ERC-4337 EntryPoint v0.7Canonical ERC-4337 v0.7 EntryPoint singletonOfficial0x00000000...f37da032
Multicall3Canonical batch and read aggregatorOfficial0xcA11bde0...3976CA11
Safe Multisig FactorySafe 1.3.0 proxy factory for 2-of-3 multisig governance & treasuryGovernance0xa6B71E26...6a896AB2
Uniswap v4 PoolManagerSingleton liquidity manager for Elysium private poolsStage 2Stage 2 Planned—
PinelyHookUniswap v4 BaseHook: Machine, Policy, Freeze & Tier guardsStage 2Stage 2 Planned—
PinelyRouterStateless swap router binding machine session key to pool via hookDataStage 2Stage 2 Planned—
BurnVaultProtocol fee recipient & permissionless $PINELY burnerStage 2Stage 2 Planned—
PinelyStakeReputational staking vault with 7-day timelock cooldownStage 2Stage 2 Planned—
Critical Nitro Block Time Guidelines (100–200 ms)

Arbitrum Nitro Orbit on Elysium produces blocks every 100–200ms. Never assume block.number as a unit of time. Always evaluate daily limits, cooldowns, and authorization deadlines strictly using block.timestamp. In addition, viem's built-in elysiumTestnet refers to a legacy chain (1338); always import the canonical chain configuration from @pinely/shared/chains.