Bootcamp

Implementation boundary

Read-only Explorer history is provider-reported, even when status says SUCCESS. A signed quote proves terms, not settlement. Guard acceptance is not funding. Keep Tidepool testnet evidence separate from official 1Click.

Implementation boundary

ANY_INPUT is an ongoing collector: the supplied documentation specifies a $1,000 sweep threshold, no refunds, and partner authorization. This is not a universal minimum for ordinary swaps. Its creation deadline does not expire the collector. Do not enable ongoing collection under a one-payment mandate.

Implementation boundary

Distinguish protocol, provider, application, network and withdrawal costs. Do not automatically add another website’s distribution fee. Price improvements may be shared; failed swaps can still incur costs. Confidential swaps have a separate fee arrangement. No application fee is activated here.

Implementation boundary

The supplied narrative contradicted its 75-minute example. This lab explicitly adopts the capped example, not an asserted provider rule. Invalid estimates fail closed. Never mutate a signed quote: request a fresh quote, verify its signature, and rerun policy checks.

Implementation boundary

The BTC connector refund flow is specific to a deposit that never finalized. It requires a request, timelock, execution and MPC signing. Check actual state and current required storage deposit; never automate refunds from this lesson. BTC/ZEC withdrawals may use single-use inputs, so treasury-sender matching alone is insufficient.

Implementation boundary

For deposits from Hyperliquid, the guide specifies 0.5 USDC minimum and 0.2 USDC fee. sendAsset/spotSend use quoted amountIn; usdSend additionally needs 1 USDC. Verify current quotes and supported methods. Direct bridge transfers to a quote address are not guaranteed. Derivatives access is not enabled here.

Implementation boundary

Display the actual provider, receipt asset, withdrawal conditions, lockups and costs before owner approval. Availability through the API is not an audit or endorsement. This site has no enabled Earn execution path.

Implementation boundary

The incident API does not expose every surface security mode. Do not translate operational into Usual, or an incident into Under attack. Stale, malformed or unavailable data is unknown. Public views exclude internal descriptions, metadata and actor details. No incident submission is implemented.

Implementation boundary

Use swap_hash for deduplication after selection; update delivery estimates until liquidity is delivered. Confirm deadline units and how the escrow flow interacts with firm-quote obligations before live work. Do not fill coordinated self-originated hackathon intents. No solver bus connection or signing is enabled.

Implementation boundary

The API has a general 24-hour data-retention limit with a narrow history exception; solver obligations require seven-year records. Keep these stores and purposes distinct. Provider order flow must not feed unrelated model training. Do not infer endorsement or audit coverage for X3.

Implementation boundary

Preserve depositAddress and depositMemo together, use fresh deadlines, and distinguish dry quote simulation from mainnet execution. FAILED does not establish REFUNDED. Never paste credentials into lessons or commit them.

Implementation boundary

Treasury references identify entities and address roles, not approved recipients or a proof of swap causality. Follow current official documentation and review source dates.

The owner writes authority; the agent proposes actions

An intent describes a requested outcome: the input asset and amount, recipient, route, constraints, deadline and failure behavior. A mandate separately states what an agent is allowed to request. Model output is input to the checker, never an authorization by itself.

X3 Shield combines policy compilation, quote checks and a NEAR Guard contract. These are distinct stages. Passing a browser check proves a local calculation over supplied data. It does not prove live mandate state, a wallet signature, a transfer or finalized delivery.

X3 Shield and official NEAR SHIELD

X3 Shield is this project’s .x3 compiler, owner-mandate checks and NEAR Guard workflow. Official NEAR Intents SHIELD is a separate incident and security-policy service used by integrated NEAR Intents surfaces. A shared name does not establish integration, endorsement or equivalent enforcement.

Two toolchains, two contracts with the developer

The Python intent/mandate tools are the shipping NEAR adapter surface. near_intents.py prepares and checks requests; near_mandate.py compiles owner policies. The Rust x3c compiler has a broader language surface, produces X3BC and runs with a local VM and capability host. The documented Rust instruction set is not loaded by a chain pallet.

Choose your target before copying syntax. A clause accepted by a parser is not necessarily lowered or enforced by a particular backend. In particular, the generic Rust VM has no mandate store: under mandate does not create wallet enforcement.

Start from a known revision

Use Python 3.11+, Rust 1.90+ with Cargo, and Node.js 22+ for browser tests. Installation downloads dependencies; the subsequent fixture-based lessons need no wallet or signing key. The browser lab below uses an independently pinned, older checker; its revision is displayed rather than silently equated with current master.

git clone https://github.com/Cyptopimpinainteazy/x3lang.git
cd x3lang
git checkout 3b6c73037a1cb158f79c5f76d3ee202c4376f8d4
python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install -r x3-lang/requirements.txt pytest
git rev-parse HEAD

Select the entry point

cli.py is a parser boundary that emits a JSON AST for one intent. It intentionally skips other top-level declarations; using it alone cannot validate a whole Rust program or certify its policy enforcement. Use the adapter for NEAR lowering and x3c for the Rust surface. Ask each CLI for its supported arguments at your pinned revision.

python3 x3-lang/cli.py x3-lang/examples/near_intents_agent_payment.x3
python3 x3-lang/near_intents.py --help
cargo run --manifest-path x3-lang/Cargo.toml --locked -p x3-tools --bin x3c -- --help

The program envelope

intent NAME { ... } declares the payment program. from names chain.asset, an integer amount and the source receiver. to names the destination asset and its receiver. route encloses operations, with semicolons on the route steps in the examples. Use the complete checked-in example below as your starting point.

In the Python surface, blank lines and full-line // or # comments are ignored; trailing comments are supported by its line cleaner. That does not make the syntax rules of every other frontend identical. Keep examples formatted like their target’s checked-in files.

Constraints are obligations

require slippage <= 0.5% sets an upper bound; require fees <= 100 bps sets a fee ceiling. require nonce unused NAME names a one-use identifier. under mandate OWNER associates the intent with an owner’s policy; it is not a declaration of that policy.

timeout 10m refund Solana.USDC specifies a refund path at the deadline. On the NEAR adapter, on_fail rollback is translated into refund semantics; it is not an instantaneous cross-chain reversal. An unsupported halt or quarantine promise is refused. The generic Rust path has its own policy checks.

Base units are integers

Amounts are integer base units, not display decimals. For a token with six decimals, 25 units is 25000000. Check token metadata rather than guessing decimals from a symbol. The mandate amount must fit u128; per_payment must be positive and cannot exceed per_24h.

One basis point is 0.01%; 50 bps is 0.5%. The Rust guide documents bare 50 and 0.5% as equivalent slippage bounds, and 100 bps or 100bps for fee ceilings. Use the demonstrated percent/bps spellings in the NEAR track. A cap is not a promise that a quote will meet it.

Symbols are not token identities

Chain aliases and symbols are resolved through registries and token records. A registry entry is not evidence of a deployed integration. Resolve a concrete originAsset/destinationAsset from the token catalog and bind the correct network. Do not substitute similarly named tokens or compare Solana addresses case-insensitively.

The parser accepts some short EVM placeholders for source compatibility. Passing its address-shape check does not prove a real address, ownership, network or recipient intent. Example accounts are teaching fixtures, not deposit instructions.

Relative time needs a clock

A mandate expires duration is compiled relative to compilation time. The checker requires now to be strictly before expiry and the payment deadline to be no later than mandate expiry. Recompiling later changes the computed expiry even when the source is unchanged. Record both source hash and evaluation time.

The local lab deliberately freezes the clock to the scenario fixture timestamp. Its old-looking expiry is not a statement about a currently active on-chain mandate.

Identity and spend scope

owner identifies the NEAR owner; agent identifies the account acting under the mandate. spend fixes the origin asset. per_payment bounds one payment, while per_24h bounds a rolling 24-hour window. These are not interchangeable: a small payment can still exhaust a rolling allowance.

allow recipients is a list of permitted destination accounts; allow assets is a list of permitted destination assets. Lists must be nonempty, distinct and within the implementation’s length limits. refund_to pins an explicit source-chain account, not the symbolic sender.

Price bounds and approvals

Both require slippage and require fees must be bounded. If multiple bounds are present, lowering uses the tightest. Compiled ceilings cannot exceed 10000 bps. The payment’s declared caps must not loosen the owner’s caps.

approve above AMOUNT by N of ACCOUNTS makes payments strictly above AMOUNT require approvals. Equality is not above. The approval amount must be below per_payment, approvers must be distinct and valid, N must be between one and the number of approvers, and the agent cannot approve its own payments.

Expiry, history and revocation

expires ends the authority at a computed time. The rolling check sums payments strictly inside its 24-hour window and also caps payment count. The checked-in example describes a maximum of 64 payments per window. A locally compiled mandate has no real spend history or revocation state unless you supply state.

A deployed Guard maintains state and must recheck authority when accepting the request. Revocation and replay are stateful contract concerns. Never turn an old local pass into a current authorization. The source hash records identity; each execution path must actually enforce the binding to make it meaningful.

One leg with matching endpoints

The adapter accepts one NearIntents bridge leg and no fallback route. Its origin and destination assets must match the intent endpoints. A second swap or a fallback is not silently treated as part of an atomic transaction.

An explicit slippage bound and timeout are required. A mandate payment requires exactly one replay-protection nonce. Refunds must use the deposited asset on the origin chain, and timeout/on_fail refund destinations must agree.

No unenforceable promises

Only guards supported by this adapter may pass lowering. A broader compiler vocabulary is not a license to attach unsupported guards to a NEAR request. X3_NEAR_GUARD_UNENFORCEABLE means the selected backend cannot keep the promise.

The searchable refusal index below is extracted from the pinned Python parser, adapter and mandate compiler. It includes exact source locations. It is a diagnostic index for those files, not a claim that it exhausts the Rust verifier, VM traps or deployed contract errors.

Choose the integration level

1Click is the higher-level cross-chain swap workflow: request a quote, fund the reviewed deposit, then track the result. The Intents SDK exposes lower-level intent execution and withdrawal operations. It is a separate integration surface, not another name for the .x3 compiler or the 1Click SDK libraries.

Official NEAR Intents has no testnet version according to its quickstart. The historical Base Sepolia to NEAR testnet Tidepool route is a separate trusted-relay experiment; it is not official 1Click testnet settlement. An explorer or distribution-channel API key provides access, not a funded-swap receipt or proof of destination settlement.

Plan without requesting a quote

plan compiles an intent into a quote request. It does not ask for a quote. Supplying --tokens uses a saved token catalog; omitting it fetches the live catalog. tokens.json below is a catalog you obtain and review, not a file that this page installs.

python3 x3-lang/near_intents.py plan \
  x3-lang/examples/near_intents_agent_payment.x3 --tokens tokens.json
python3 x3-lang/near_intents.py mandate check \
  x3-lang/examples/near_mandate_agent.x3 \
  x3-lang/examples/near_intents_agent_payment.x3 --tokens tokens.json

Call the CLI with an argument array

For a server integration, run the pinned tool in a constrained process, pass paths as arguments, and parse its JSON output. Never concatenate untrusted .x3 source into a shell command. Nonzero exit is a refusal or failure to handle, not permission to fall back to an unchecked request.

Use an allowlisted working directory, cap input/output size and runtime, and keep source separate from credentials. This example only runs the offline plan with a supplied catalog.

import json, subprocess
result = subprocess.run(
    ["python3", "x3-lang/near_intents.py", "plan",
     "payment.x3", "--tokens", "tokens.json"],
    capture_output=True, text=True, timeout=30, check=False,
)
if result.returncode != 0:
    raise RuntimeError(result.stderr or "X3 plan refused")
plan = json.loads(result.stdout)

Browser integration

This site vendors the browser checker with hashes and a provenance record. Its judge.evaluate function accepts the scenario dataset and an intent/state scenario, then returns a decision, checks and denied_guards. The lab uses that code directly. It performs no remote quote request or transaction.

The browser port is not a complete Rust compiler SDK. To add a new language feature, change the authoritative implementation and parity tests first, then refresh the vendored files and hashes.

Dry quote is a network operation

quote defaults to dry mode and calls the quote service. It checks the response against the program and can write structured evidence with --out. A dry quote is not a settlement or proof that a deposit exists. Token availability and service responses can change.

python3 x3-lang/near_intents.py quote \
  x3-lang/examples/near_intents_agent_payment.x3 \
  --mandate x3-lang/examples/near_mandate_agent.x3 \
  --tokens tokens.json --out dry-quote.json

Bind the response before using it

Validate the configured manager signature, exact signed payload and quote hash, then check freshness, amount, assets, recipient, deadline, refund and price bounds. A valid signature does not itself mean the quote meets the owner’s policy. A provider status string does not prove chain finality.

--live is a separate operational step: it requests a real deposit address, consumes local nonce state and writes a receipt. It does not sign the deposit. This course does not run it. Review the exact network, accounts, amounts and receipt before any separate wallet authorization.

Generate arguments, do not assume they were sent

mandate args produces create_mandate arguments. mandate revoke produces revoke_mandate arguments. These commands print data or a command; generating revocation arguments does not revoke anything on-chain. Guard calls need the correct signer, network, contract, gas and attached deposit.

python3 x3-lang/near_intents.py mandate args \
  x3-lang/examples/near_mandate_agent.x3 --tokens tokens.json
python3 x3-lang/near_intents.py prepare \
  --receipt reviewed.near-receipt.json --program payment.x3

Authorization is separate from custody

Agent methods register and accept a request under the mandate, and listed approvers use the contract’s approval path where required. Read the contract method definitions and generated arguments at your revision rather than inventing JSON fields or using an old contract ABI.

The Guard described in this track holds no funds. A keyholder can bypass it by directly using the origin wallet. A scoped vault can change that architecture only after its code, authority boundaries and deployed instance have been independently verified.

Observe and verify the result

status reports an observed outcome. verify-deposit and verify-settlement perform their respective evidence checks and update a receipt. submit-deposit notifies 1Click of a transaction hash only after the implemented checks; it is an external side effect, not a read-only query.

Record the exact source hash, quote binding, authorization transaction, origin transfer and destination evidence. A local receipt or two unrelated transaction hashes cannot establish cross-chain causality by themselves.

Compilation stages

The documented pipeline is source → lexer/parser → typed AST → semantic checks → X3IR → X3BC emitter → bytecode verifier → VM. Each stage answers a different question. Parsing recognizes syntax; semantics reject unsupported claims; verification checks the instruction stream; execution needs an actual host.

Determinism means the same source, compiler revision and options produce the same result. Pin all three. A bytecode file is not a signed transaction. Local VM gas is not a host chain’s fee quote.

cargo run --manifest-path x3-lang/Cargo.toml --locked -p x3-tools --bin x3c -- check x3-lang/examples/simple_swap.x3
cargo run --manifest-path x3-lang/Cargo.toml --locked -p x3-tools --bin x3c -- build x3-lang/examples/simple_swap.x3 -o /tmp/simple_swap.x3b
cargo run --manifest-path x3-lang/Cargo.toml --locked -p x3-tools --bin x3c -- explain /tmp/simple_swap.x3b

General programs and host effects

The Rust compiler accepts functions, bindings, mutation, branches, loops, returns, function types, tuples and arrays. The checked-in events_and_host_calls example below demonstrates fn main, emit, subscription, @subscribe and @sponsor without inventing an SDK.

A capability call names an external effect; a matching capability host must implement it. A compiled subscription is not evidence that a keeper is running. Inspect the parser and tests for precise grammar and type combinations; do not assume every Rust-looking construct is part of .x3.

The guard vocabulary

The Python registry includes finality, slippage, fees, profit, invariant, risk, nonce, audit_gate, bridge_liquidity, canonical_supply, relayer_quorum, route_score, solver_bond, proof_complete, refund_path, refund_to, finality_explicit, vm_supported and mainnet_safe. It also accepts the legacy spelling proof. The parser’s vocabulary does not assert that every backend enforces all of them.

The Rust guide identifies X3E4027 for a fee ceiling without backing policy. GuardClaimUnbacked means no pass can substantiate a claim. Do not remove a safety condition merely to get a green compiler result; select a supported target or implement the missing checker and adversarial tests.

Evidence must come from somewhere

proofs required records obligations such as source_lock_proof and destination_fill_proof. It does not manufacture evidence. Verification against a supplied root is not the same as authenticating the root against an independent trust anchor.

The documented NEAR light-client boundary does not establish an independently authenticated production checkpoint, deployed escrow code hash or terminal escrow storage state. Treat RPC agreement, verified=true fields and trusted flags as data to evaluate, never consensus proof.

Rollback scope is target-specific. A local transaction journal cannot undo an already-finalized external chain action. For the NEAR quote path, refunds follow the adapter/service semantics; do not describe a multichain route as atomic merely because the source says rollback.

Make refusal a tested behavior

Start with a valid fixture. Change one property at a time: recipient, origin or destination asset, amount, fee cap, slippage cap, refund address, nonce or deadline. Assert the specific failed guard or compiler code. Then test boundary equality, expiry, revocation, rolling spend and duplicate submissions at the layer that owns that state.

Keep browser/Python parity tests and contract tests distinct. A replay contract test is not a browser replay defense. Never repair a failed test by fabricating chain state or replacing a verifier with a success flag.

PYTHONPATH=x3-lang python3 -m pytest x3-lang/tests -q
node --test x3-lang/near/demo/test/*.test.mjs
cargo test --manifest-path x3-lang/Cargo.toml --locked -p x3-lang-vm --quiet
cargo test --manifest-path x3-lang/near/x3-guard/Cargo.toml --locked --quiet

A reproducible handoff

Include source revision and hash, compiler/tool versions, token catalog identity, evaluation time, generated terms, exact test commands and results. Label local, fixture, dry-network, testnet and independently verified settlement evidence separately.

Keep private keys, seed phrases and API credentials out of source, screenshots and receipts. Review generated files before publication. Require independent review before enabling a signer or payout. Graduation here is local learning progress, not a certification of deployment safety.