Overview
Thepolicy field on SinkerConfig lets you set guardrails on what the AI agent is allowed to do, directly in your application code. No config file, no restart — just pass it at construction time.
policy: {} is the same as not providing policy at all.
max-queue and rate-limit are sidecar-side operator settings and are not available here.
Set them with sinker policy set on the CLI.PolicyConfig
Tip controls
Hard ceiling on tip size (lamports). The agent cannot recommend above this value
regardless of what current network conditions suggest.
Tip cannot exceed N% of the transaction’s transfer value.
For example,
3 means the tip is capped at 3% of the amount being transferred.The percentile the agent targets when the network is calm.
p75 is a good balance between landing rate and cost for most use cases.
Use p95 or p99 for time-sensitive transactions.Maximum age of tip oracle data in milliseconds before the agent refuses to proceed.
The oracle updates every ~10 seconds; setting this below 400ms (one slot) will cause the
agent to always see the data as stale.
Bundle & retry controls
Maximum number of re-submission attempts before the bundle is declared expired and dropped.
How many slots past the enqueue slot the agent keeps retrying before dropping the bundle.
At ~400ms per slot, 150 slots is about 60 seconds.
Maximum tip increase per retry cycle (lamports). Prevents the agent from doubling or
tripling the tip in a single escalation step.Must be less than or equal to
maxTipLamports — the constructor throws SinkerPolicyError
if escalationStepLamports > maxTipLamports.Priority tier for all bundles submitted through this instance.
auto lets the agent choose based on network conditions.
Pin to high or urgent when every transaction is time-sensitive.Built-in defaults
| Key | Default | Unit |
|---|---|---|
maxTipLamports | 500000 | lamports |
maxTipRatioPct | 5.0 | % |
tipPercentile | p75 | — |
staleAfterMs | 2000 | ms |
maxRetries | 3 | — |
expirySlots | 150 | slots |
escalationStepLamports | 5000 | lamports |
priority | auto | — |
Constructor validation
TheSinker constructor validates the policy immediately on instantiation.
Hard errors → throws SinkerPolicyError (construction fails):
| Condition | Error |
|---|---|
escalationStepLamports > maxTipLamports | Every retry would immediately exceed the tip ceiling |
maxTipLamports === 0 | Jito requires a non-zero tip — all bundles will be rejected |
maxTipRatioPct <= 0 | Invalid — would block all tips |
expirySlots === 0 | Bundles expire immediately and can never be submitted |
console.warn (construction continues):
| Condition | Warning |
|---|---|
staleAfterMs < 400 | Shorter than one slot — oracle may always appear stale |
maxTipRatioPct > 100 | Tip can be larger than the transaction value |
maxRetries === 0 | Failed bundles will not be retried |
sinker.policy
The resolved policy — all defaults filled in — is available after construction assinker.policy.
ResolvedPolicy — all 8 fields present, no optionals.
sinker.validatePolicy()
Returns{ errors, warnings, valid } without throwing. Use this if you want to inspect
the policy programmatically after construction without relying on try/catch.
PolicyValidationResult
Hard problems that will cause incorrect operation.
Unusual values that may be intentional but are worth knowing about.
true when errors is empty. Warnings do not affect valid.SinkerPolicyError
Thrown by the constructor when the policy has hard errors.Relationship to sinker.policy.json
The CLI’ssinker.policy.json and the SDK’s policy config are independent. The CLI file controls what the sidecar and agent enforce at the process level. The SDK policy is in-memory config on the client side.
In practice: set your hard system-wide limits in sinker.policy.json via the CLI, and set per-application constraints in the SDK policy config. The agent will respect whichever is more restrictive.
| Setting | Scope | How to set |
|---|---|---|
max-queue, rate-limit | Sidecar-wide | CLI only (sinker policy set) |
| Tip caps, retry limits, priority | Per application | SDK policy config |
| Both sets | System-wide persistent | CLI + sinker.policy.json |