diff --git a/docs/AGENTS.md b/docs/AGENTS.md index a0c8ccfb4..e3a25e3cd 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -57,9 +57,10 @@ npx skills add base/base-skills |Specifications/Specifications/Base Protocol/Bridging:specifications/base-protocol/bridging/standard-bridges,specifications/base-protocol/bridging/deposits,specifications/base-protocol/bridging/withdrawals,specifications/base-protocol/bridging/cross-domain-messengers,specifications/base-protocol/bridging/base-solana-bridge |Specifications/Specifications/Base Protocol/Proofs:specifications/base-protocol/proofs/overview,specifications/base-protocol/proofs/challenger,specifications/base-protocol/proofs/proposer,specifications/base-protocol/proofs/registrar,specifications/base-protocol/proofs/tee-prover,specifications/base-protocol/proofs/zk-prover,specifications/base-protocol/proofs/proof-contracts |Specifications/Specifications/B20:specifications/b20/specification-overview,specifications/b20/reference/constants-addresses,specifications/b20/reference/errors-events,specifications/b20/reference/invariants-tests,specifications/b20/changelog -|Specifications/Specifications/B20/Interfaces:specifications/b20/reference/interfaces/i-activation-registry,specifications/b20/reference/interfaces/ib20,specifications/b20/reference/interfaces/ib20-asset,specifications/b20/reference/interfaces/ib20-factory,specifications/b20/reference/interfaces/ib20-stablecoin,specifications/b20/reference/interfaces/i-policy-registry +|Specifications/Specifications/B20/Interfaces:specifications/b20/reference/interfaces/i-activation-registry/index,specifications/b20/reference/interfaces/ib20/index,specifications/b20/reference/interfaces/ib20-asset/index,specifications/b20/reference/interfaces/ib20-factory/index,specifications/b20/reference/interfaces/ib20-stablecoin/index,specifications/b20/reference/interfaces/i-policy-registry/index |Specifications/Specifications/Transactions:specifications/transactions/transaction-ordering,specifications/transactions/transaction-finality,specifications/transactions/network-fees,specifications/transactions/throughput-and-limits,specifications/transactions/troubleshooting-transactions |Specifications/Specifications/Builder Codes:specifications/builder-codes/overview,specifications/builder-codes/for-app-developers,specifications/builder-codes/for-wallet-developers,specifications/builder-codes/for-agent-developers +|Specifications/Specifications/Validity Transactions:specifications/build-transaction/validity-transactions,specifications/build-transaction/build-a-validity-transaction,specifications/build-transaction/base_sendRawTransactionValidity,specifications/build-transaction/fees-ordering-and-lifecycle,specifications/build-transaction/predicates-and-safety,specifications/build-transaction/troubleshooting |Specifications/Reference:specifications/reference/base-contracts,specifications/reference/smart-contracts,specifications/reference/configuration,specifications/reference/glossary |Specifications/Node Operators:specifications/node-operators/run-a-node,specifications/node-operators/performance-tuning,specifications/node-operators/snapshots,specifications/node-operators/troubleshooting |Specifications/Security:specifications/security/security-council-for-base,specifications/security/avoid-malicious-flags,specifications/security/report-a-vulnerability diff --git a/docs/docs.json b/docs/docs.json index fd3aacab8..32765db79 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -266,6 +266,17 @@ "specifications/builder-codes/for-wallet-developers", "specifications/builder-codes/for-agent-developers" ] + }, + { + "group": "Validity Transactions", + "pages": [ + "specifications/build-transaction/validity-transactions", + "specifications/build-transaction/build-a-validity-transaction", + "specifications/build-transaction/base_sendRawTransactionValidity", + "specifications/build-transaction/fees-ordering-and-lifecycle", + "specifications/build-transaction/predicates-and-safety", + "specifications/build-transaction/troubleshooting" + ] } ] }, diff --git a/docs/llms-full.txt b/docs/llms-full.txt index 0312f6bf4..59cda2446 100644 --- a/docs/llms-full.txt +++ b/docs/llms-full.txt @@ -280,17 +280,17 @@ const client = createPublicClient({ chain: base, transport: http() }) ##### Interfaces -- [IActivationRegistry Reference](https://docs.base.org/specifications/b20/reference/interfaces/i-activation-registry): Generated B20 reference for IActivationRegistry functions, events, and errors. +- [IActivationRegistry Reference](https://docs.base.org/specifications/b20/reference/interfaces/i-activation-registry/index): Generated B20 reference for IActivationRegistry functions, events, and errors. -- [IB20 Reference](https://docs.base.org/specifications/b20/reference/interfaces/ib20): Generated B20 reference for IB20 functions, events, and errors. +- [IB20 Reference](https://docs.base.org/specifications/b20/reference/interfaces/ib20/index): Generated B20 reference for IB20 functions, events, and errors. -- [IB20Asset Reference](https://docs.base.org/specifications/b20/reference/interfaces/ib20-asset): Generated B20 reference for IB20Asset functions, events, and errors. +- [IB20Asset Reference](https://docs.base.org/specifications/b20/reference/interfaces/ib20-asset/index): Generated B20 reference for IB20Asset functions, events, and errors. -- [IB20Factory Reference](https://docs.base.org/specifications/b20/reference/interfaces/ib20-factory): Generated B20 reference for IB20Factory functions, events, and errors. +- [IB20Factory Reference](https://docs.base.org/specifications/b20/reference/interfaces/ib20-factory/index): Generated B20 reference for IB20Factory functions, events, and errors. -- [IB20Stablecoin Reference](https://docs.base.org/specifications/b20/reference/interfaces/ib20-stablecoin): Generated B20 reference for IB20Stablecoin functions, events, and errors. +- [IB20Stablecoin Reference](https://docs.base.org/specifications/b20/reference/interfaces/ib20-stablecoin/index): Generated B20 reference for IB20Stablecoin functions, events, and errors. -- [IPolicyRegistry Reference](https://docs.base.org/specifications/b20/reference/interfaces/i-policy-registry): Generated B20 reference for IPolicyRegistry functions, events, and errors. +- [IPolicyRegistry Reference](https://docs.base.org/specifications/b20/reference/interfaces/i-policy-registry/index): Generated B20 reference for IPolicyRegistry functions, events, and errors. - [Constants & Addresses](https://docs.base.org/specifications/b20/reference/constants-addresses): Copy B20 precompile addresses, roles, policy scopes, variant bytes, policy IDs, and supply-cap constants. @@ -326,6 +326,20 @@ const client = createPublicClient({ chain: base, transport: http() }) - [Builder Codes for Agent Developers](https://docs.base.org/specifications/builder-codes/for-agent-developers): Attribute your AI agent's onchain transactions to your identity on Base and unlock analytics and leaderboard features. +#### Validity Transactions + +- [Overview](https://docs.base.org/specifications/build-transaction/validity-transactions): Submit signed transactions that Base considers when onchain conditions match. + +- [Build a Validity Transaction](https://docs.base.org/specifications/build-transaction/build-a-validity-transaction): Sign and submit a validity transaction with Viem. + +- [Validity Transaction RPC](https://docs.base.org/specifications/build-transaction/base_sendRawTransactionValidity): Submit a signed raw transaction with validity predicates. + +- [Fees, Ordering, and Lifecycle](https://docs.base.org/specifications/build-transaction/fees-ordering-and-lifecycle): Understand fees, expiry, and replacement for validity transactions. + +- [Predicates and Safety](https://docs.base.org/specifications/build-transaction/predicates-and-safety): Use validity predicates safely. + +- [Troubleshooting](https://docs.base.org/specifications/build-transaction/troubleshooting): Diagnose validity transaction submission and inclusion issues. + ### Reference - [Contract Addresses](https://docs.base.org/specifications/reference/base-contracts): A comprehensive list of contract addresses for Base Mainnet and Base Testnet, including links to their respective blockchain explorers. diff --git a/docs/llms.txt b/docs/llms.txt index 461b97bf6..431d03720 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -214,17 +214,17 @@ ##### Interfaces -- [IActivationRegistry Reference](https://docs.base.org/specifications/b20/reference/interfaces/i-activation-registry): Generated B20 reference for IActivationRegistry functions, events, and errors. +- [IActivationRegistry Reference](https://docs.base.org/specifications/b20/reference/interfaces/i-activation-registry/index): Generated B20 reference for IActivationRegistry functions, events, and errors. -- [IB20 Reference](https://docs.base.org/specifications/b20/reference/interfaces/ib20): Generated B20 reference for IB20 functions, events, and errors. +- [IB20 Reference](https://docs.base.org/specifications/b20/reference/interfaces/ib20/index): Generated B20 reference for IB20 functions, events, and errors. -- [IB20Asset Reference](https://docs.base.org/specifications/b20/reference/interfaces/ib20-asset): Generated B20 reference for IB20Asset functions, events, and errors. +- [IB20Asset Reference](https://docs.base.org/specifications/b20/reference/interfaces/ib20-asset/index): Generated B20 reference for IB20Asset functions, events, and errors. -- [IB20Factory Reference](https://docs.base.org/specifications/b20/reference/interfaces/ib20-factory): Generated B20 reference for IB20Factory functions, events, and errors. +- [IB20Factory Reference](https://docs.base.org/specifications/b20/reference/interfaces/ib20-factory/index): Generated B20 reference for IB20Factory functions, events, and errors. -- [IB20Stablecoin Reference](https://docs.base.org/specifications/b20/reference/interfaces/ib20-stablecoin): Generated B20 reference for IB20Stablecoin functions, events, and errors. +- [IB20Stablecoin Reference](https://docs.base.org/specifications/b20/reference/interfaces/ib20-stablecoin/index): Generated B20 reference for IB20Stablecoin functions, events, and errors. -- [IPolicyRegistry Reference](https://docs.base.org/specifications/b20/reference/interfaces/i-policy-registry): Generated B20 reference for IPolicyRegistry functions, events, and errors. +- [IPolicyRegistry Reference](https://docs.base.org/specifications/b20/reference/interfaces/i-policy-registry/index): Generated B20 reference for IPolicyRegistry functions, events, and errors. - [Constants & Addresses](https://docs.base.org/specifications/b20/reference/constants-addresses): Copy B20 precompile addresses, roles, policy scopes, variant bytes, policy IDs, and supply-cap constants. @@ -260,6 +260,20 @@ - [Builder Codes for Agent Developers](https://docs.base.org/specifications/builder-codes/for-agent-developers): Attribute your AI agent's onchain transactions to your identity on Base and unlock analytics and leaderboard features. +#### Validity Transactions + +- [Overview](https://docs.base.org/specifications/build-transaction/validity-transactions): Submit signed transactions that Base considers when onchain conditions match. + +- [Build a Validity Transaction](https://docs.base.org/specifications/build-transaction/build-a-validity-transaction): Sign and submit a validity transaction with Viem. + +- [Validity Transaction RPC](https://docs.base.org/specifications/build-transaction/base_sendRawTransactionValidity): Submit a signed raw transaction with validity predicates. + +- [Fees, Ordering, and Lifecycle](https://docs.base.org/specifications/build-transaction/fees-ordering-and-lifecycle): Understand fees, expiry, and replacement for validity transactions. + +- [Predicates and Safety](https://docs.base.org/specifications/build-transaction/predicates-and-safety): Use validity predicates safely. + +- [Troubleshooting](https://docs.base.org/specifications/build-transaction/troubleshooting): Diagnose validity transaction submission and inclusion issues. + ### Reference - [Contract Addresses](https://docs.base.org/specifications/reference/base-contracts): A comprehensive list of contract addresses for Base Mainnet and Base Testnet, including links to their respective blockchain explorers. diff --git a/docs/specifications/build-transaction/base_sendRawTransactionValidity.mdx b/docs/specifications/build-transaction/base_sendRawTransactionValidity.mdx new file mode 100644 index 000000000..cda73c2dd --- /dev/null +++ b/docs/specifications/build-transaction/base_sendRawTransactionValidity.mdx @@ -0,0 +1,69 @@ +--- +title: "Validity Transaction RPC" +sidebarTitle: "Validity Transaction RPC" +description: "Submit a signed raw transaction with validity predicates." +--- + +Submits a signed legacy, EIP-2930, or EIP-1559 transaction with predicates that control when Base can include it. EIP-1559 is recommended. + + +This experimental method is currently available on Vibenet. The production API contract is not yet confirmed. + + +## Parameters + +Pass two parameters. The first is a signed, serialized transaction. The second contains a non-empty `validity` array. + + +```json Request lines wrap expandable +{ + "jsonrpc": "2.0", + "id": 1, + "method": "base_sendRawTransactionValidity", + "params": [ + "0x", + { + "validity": [ + { + "type": "storage", + "params": { + "address": "0x8ba1f109551bD432803012645Ac136ddd64DBA72", + "slot": "0x8", + "mask": "0xff", + "op": "=", + "value": "0x2a" + } + } + ] + } + ] +} +``` + + +## Predicates + +| Type | Parameters | +| --- | --- | +| `balance` | `address`, `op`, `value` | +| `storage` | `address`, `slot`, `op`, `value`, optional `mask` | +| `block_number` | `op`, `value` | +| `flashblock_index` | `op`, `value` | + +The supported operators are `<`, `<=`, `=`, `!=`, `>`, and `>=`. Predicate values use `0x`-prefixed hexadecimal strings. The `mask` defaults to all ones. + +## Returns + + + The 32-byte hash of the submitted transaction. + + +Returning a hash confirms acceptance. It does not confirm inclusion. + +## Errors + +The method returns JSON-RPC errors. Handle an unavailable method, invalid parameters, and a missing transaction hash. + +Error codes and messages are not yet stable. + +Read [Predicates and Safety](/specifications/build-transaction/predicates-and-safety) for evaluation rules. Read [Troubleshooting](/specifications/build-transaction/troubleshooting) when a transaction is not included. \ No newline at end of file diff --git a/docs/specifications/build-transaction/build-a-validity-transaction.mdx b/docs/specifications/build-transaction/build-a-validity-transaction.mdx new file mode 100644 index 000000000..97a908e6f --- /dev/null +++ b/docs/specifications/build-transaction/build-a-validity-transaction.mdx @@ -0,0 +1,104 @@ +--- +title: "Build a Validity Transaction" +description: "Sign and submit a validity transaction with Viem." +--- + +This guide uses an EIP-1559 transaction with Viem because it is the recommended transaction type. The API also supports signed legacy and EIP-2930 transactions. + + +Validity Transactions are experimental. `base_sendRawTransactionValidity` is currently available on Vibenet. + + +## 1. Create Predicates + +Use `balance` or `storage` to wait for account or contract state. Use `block_number` and `flashblock_index` to constrain the candidate position. Every predicate must match. + +```ts Predicate setup lines wrap expandable +import type { Address, Hex } from 'viem'; + +const validity = [ + { + type: 'balance', + params: { + address: '0x8ba1f109551bD432803012645Ac136ddd64DBA72' as Address, + op: '>=', + value: '0x1' as Hex, + }, + }, + { + type: 'storage', + params: { + address: '0x8ba1f109551bD432803012645Ac136ddd64DBA72' as Address, + slot: '0x8' as Hex, + op: '=', + value: '0x2a' as Hex, + }, + }, + { + type: 'block_number', + params: { op: '<=', value: '0x11a6a1' as Hex }, + }, + { + type: 'flashblock_index', + params: { op: '<=', value: '0x2' as Hex }, + }, +] as const; +``` + +Omit `mask` to compare the full storage word. Use `flashblock_index` to target a position within a Flashblock. + +## 2. Sign an EIP-1559 Transaction + +Use the sender's next nonce. The signed payload becomes the first RPC parameter. + +```ts Sign transaction lines wrap expandable +import { createPublicClient, http, type Chain } from 'viem'; +import { privateKeyToAccount } from 'viem/accounts'; + +const client = createPublicClient({ chain, transport: http(rpcUrl) }); +const account = privateKeyToAccount(privateKey); +const fees = await client.estimateFeesPerGas(); +const nonce = await client.getTransactionCount({ + address: account.address, + blockTag: 'latest', +}); + +const rawTransaction = await account.signTransaction({ + chainId: (chain as Chain).id, + type: 'eip1559', + nonce, + to: '0x...' as Address, + data: '0x...' as Hex, + value: 0n, + gas: 100_000n, + maxFeePerGas: fees.maxFeePerGas, + maxPriorityFeePerGas: fees.maxPriorityFeePerGas, +}); +``` + +## 3. Submit the Transaction + +Pass the signed transaction and `validity` as separate parameters. + +```ts Submit transaction lines wrap expandable +const response = await fetch(rpcUrl, { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ + jsonrpc: '2.0', + id: 1, + method: 'base_sendRawTransactionValidity', + params: [rawTransaction, { validity }], + }), +}); + +const body = await response.json(); +if (body.error) throw new Error(body.error.message); +const hash = body.result; +``` + +## 4. Check Inclusion + +The RPC returns a transaction hash. Use [`eth_getTransactionReceipt`](/base-chain/api-reference/ethereum-json-rpc-api/eth_getTransactionReceipt) to check for an onchain receipt. + +For field definitions, see [Validity Transaction RPC](/specifications/build-transaction/base_sendRawTransactionValidity). \ No newline at end of file diff --git a/docs/specifications/build-transaction/fees-ordering-and-lifecycle.mdx b/docs/specifications/build-transaction/fees-ordering-and-lifecycle.mdx new file mode 100644 index 000000000..d249564de --- /dev/null +++ b/docs/specifications/build-transaction/fees-ordering-and-lifecycle.mdx @@ -0,0 +1,22 @@ +--- +title: "Fees, Ordering, and Lifecycle" +description: "Understand fees, expiry, and replacement for validity transactions." +--- + +## Fees + +Transactions use the normal fee rules for their type. For EIP-1559 transactions, set `maxFeePerGas` and `maxPriorityFeePerGas` on the signed transaction. + +A transaction that is not included does not pay onchain execution fees. An included transaction pays normal execution fees, even if it reverts. + +## Ordering + +A transaction competes for inclusion only after every predicate matches. A matching predicate does not reserve block space. + +## Expiry + +Add a `block_number` predicate with a maximum block to limit a transaction's lifetime. Combine it with `flashblock_index` to tighten the expiry bound to a position within that block's Flashblocks. + +## Replacement + +A later transaction with the same sender and nonce can replace a pending transaction. If the RPC returns an underpriced-replacement error, increase the fee fields, sign again, and retry. \ No newline at end of file diff --git a/docs/specifications/build-transaction/predicates-and-safety.mdx b/docs/specifications/build-transaction/predicates-and-safety.mdx new file mode 100644 index 000000000..19c22280b --- /dev/null +++ b/docs/specifications/build-transaction/predicates-and-safety.mdx @@ -0,0 +1,69 @@ +--- +title: "Predicates and Safety" +description: "Use validity predicates safely." +--- + +Predicates are inclusion conditions. They do not guarantee inclusion or successful execution. + +## Predicate Types + +| Type | Parameters | +| --- | --- | +| `balance` | `address`, `op`, `value` | +| `storage` | `address`, `slot`, `op`, `value`, optional `mask` | +| `block_number` | `op`, `value` | +| `flashblock_index` | `op`, `value` | + +The supported operators are `<`, `<=`, `=`, `!=`, `>`, and `>=`. Predicate values use `0x`-prefixed hexadecimal strings. + +## Evaluation + +Base checks a transaction before inclusion. If a predicate is false, the transaction remains pending. + +An earlier transaction can change the balance or storage value that a pending transaction watches. The pending transaction can then become eligible in the same Flashblock. + +## Balance Example + +```json Balance predicate lines wrap expandable +{ + "type": "balance", + "params": { + "address": "0x2222222222222222222222222222222222222222", + "op": ">=", + "value": "0x1" + } +} +``` + +## Storage Example + +```json Storage predicate lines wrap expandable +{ + "type": "storage", + "params": { + "address": "0x2222222222222222222222222222222222222222", + "slot": "0x7", + "mask": "0xff", + "op": "=", + "value": "0x2a" + } +} +``` + +Base compares `(storage[address][slot] & mask)` with `value`. Omit `mask` to compare the full storage word. + +## Block and Flashblock Position + +Use `block_number` to target a block and `flashblock_index` to target a position within that Flashblock. Add separate predicates when both conditions must match. + +## Safety + +A predicate does not simulate a transaction. Keep critical checks in the application call. + +Predicates read raw storage. They cannot call view functions or evaluate computed values. Verify the target contract's storage layout before using a storage predicate. + +State can change during block building. A condition can become true or false before inclusion. + +Do not use transaction placement as a source of randomness. Do not assume a zero-valued slot makes a CREATE2 address, proxy, or uninitialized contract safe to call. + +Validity criteria are not recorded onchain. Do not include secrets in calldata or predicate values. \ No newline at end of file diff --git a/docs/specifications/build-transaction/troubleshooting.mdx b/docs/specifications/build-transaction/troubleshooting.mdx new file mode 100644 index 000000000..519ab1c30 --- /dev/null +++ b/docs/specifications/build-transaction/troubleshooting.mdx @@ -0,0 +1,36 @@ +--- +title: "Troubleshooting" +description: "Diagnose validity transaction submission and inclusion issues." +--- + +Use [`eth_getTransactionReceipt`](/base-chain/api-reference/ethereum-json-rpc-api/eth_getTransactionReceipt) to confirm onchain inclusion. + +## RPC Method Is Unavailable + +Use an endpoint that supports `base_sendRawTransactionValidity`. The method is currently available on Vibenet. + +## Submission Fails + +Confirm that the first parameter is a signed legacy, EIP-2930, or EIP-1559 transaction. Confirm that the second parameter has a non-empty `validity` array. + +Check the predicate type, operator, and `0x`-prefixed hexadecimal values. See [Validity Transaction RPC](/specifications/build-transaction/base_sendRawTransactionValidity) for the request format. + +Record the full JSON-RPC error when escalating an issue. + +## Transaction Was Not Included + +A transaction can remain pending because a predicate is false, another transaction has higher priority, it is replaced, or its maximum block or Flashblock position passed. + +## Transaction Expired + +Submit a new signed transaction with later `block_number` or `flashblock_index` conditions. + +## Replacement Is Underpriced + +Increase the fee fields, sign again, and retry with the same sender and nonce. + +## Get Help + +Include the network, RPC provider, transaction hash, predicate type, submission time, and JSON-RPC error. Do not share private keys, authentication data, or full signed transactions in public support channels. + +For community support, use the `#developer-chat` channel in the [Base Discord](https://base.org/discord). diff --git a/docs/specifications/build-transaction/validity-transactions.mdx b/docs/specifications/build-transaction/validity-transactions.mdx new file mode 100644 index 000000000..e0172c657 --- /dev/null +++ b/docs/specifications/build-transaction/validity-transactions.mdx @@ -0,0 +1,45 @@ +--- +title: "Overview" +description: "Submit signed transactions that Base considers when onchain conditions match." +tag: "Soon" +--- + +Validity Transactions let you submit a signed transaction with conditions on Base state. The API supports legacy, EIP-2930, and EIP-1559 transactions; EIP-1559 is recommended. Use them for conditional swaps, withdrawals, and other state-dependent actions. + + +Validity Transactions are experimental. `base_sendRawTransactionValidity` is currently available on Vibenet. Mainnet and Base Sepolia availability are not yet confirmed. + + +## How It Works + +Submit a signed raw transaction and a non-empty `validity` array. The current API supports balance, storage, block-number, and Flashblock-index predicates. + +A transaction is eligible only when every predicate matches. Base checks predicates before inclusion. A pending transaction can become eligible after an earlier transaction changes the state it watches. + +EIP-1559 Validity Transactions use normal fee fields. Eligibility does not reserve block space or guarantee inclusion. + +## Lifetime and Privacy + +Use `block_number` or `flashblock_index` predicates to constrain when a transaction can be included. Use the sender's nonce when replacing a pending transaction. + +Validity criteria are sent separately from the signed transaction. They do not appear in the resulting onchain transaction. Do not include secrets in calldata or predicate values. + +## Next Steps + + + + Sign and submit a transaction with Viem. + + + Review the request format. + + + Understand fees, expiry, and replacement. + + + Learn predicate rules and safety limits. + + + Diagnose submission and inclusion issues. + +