Skip to content

sora-xor/soraswap

BranchesTags

Repository files navigation

SoraSwap

SoraSwap is an Apache-2.0 Kotodama smart-contract repository for Sora Nexus. It uses the sibling ../iroha checkout as the canonical compiler, IVM runtime, CLI, and Torii toolchain.

The repo now also carries an SCCP bridge contract at contracts/bridge/sccp_bridge.ko. The deploy flow compiles and deploys it automatically with the rest of the contract set, and the signed Taira gate now verifies proof submit plus bridge-message relay through the real contract console backend.

Current status:

  • Repo scaffold is in place.
  • Initial Kotodama contracts are present for n3x, DLMM, launchpad, referral, automation, farms, perps, options, cover, solver intents, vaults, bonded operators, portfolio margin, tokenized RWA markets, and DLMM hooks.
  • Trigger-native contracts are now present for batch_amm.epoch_auction and escrow.conditional_escrow, and existing DLMM/perps/options/cover/launchpad/vault/DLMM-hook modules expose bounded pre-commit or by-call trigger callbacks.
  • The derivatives stack is being rebuilt as a launch-gated multi-contract graph: contracts/risk/risk_vault.ko, contracts/perps/perps_engine.ko, contracts/options/{manager,factory,vault,shout_option,outperformance_option}.ko, and contracts/cover/policy_manager.ko.
  • The derivatives graph now depends on sibling ../iroha support for same-transaction ABI v1 contract-to-contract call_contract(...) execution. Product contracts store deployed contract address literals as UTF-8 bytes routing fields for nested calls, while nested authority() inside the callee still resolves to the caller contract subject account.
  • DLMM is treated as the deployable AMM surface.
  • Core module config is now init-only, caller-bound, and canonical-asset based: the public *_with_assets and post-init configure_* compatibility surfaces were removed from the SoraSwap contracts.
  • The n3x basket hub now supports init-time basket targets, mint/redeem fees, redeem quoting, and mirrored fee accounting.
  • The DLMM pool scaffold now executes guarded multi-bin swaps, seeds multiple bins deterministically, and supports explicit position_id LP records with per-bin fee claims.
  • The launchpad scaffold now tracks recorded allocations, init-time claim windows, claim inventory, refunds, explicit seed inventory, registered DLMM seed plans, and executor-backed activation results on chain.
  • The risky product modules now keep executor/job ids, cadence, backlog caps, safe-mode state, and native lifecycle trigger state on the product contracts while contracts/automation/job_queue.ko remains deployed for legacy compatibility.
  • Derivatives now route user collateral, liability, and payout state through risk_vault instead of direct product-owned custody transfers. The shared risk-vault custody account is the deployed contract subject itself, so nested product calls settle against contract-owned collateral on chain. Local acceptance and the signed Taira smoke lane both exercise active write paths for perps/options/cover.
  • Perps/options/cover plus risk_vault remain one shared rollout surface behind the combined lint + compile + simulate + isolated local smoke gate rather than independent per-module acceptance.
  • The current DLMM LP surface is a single-contract scaffold, not the final helper/NFT wrapper layout.
  • New trigger-native success paths do not require an off-chain keeper/solver/relayer. Public/testnet deploy grants CanRegisterTrigger, smoke grants CanExecuteTrigger for by-call escrow evidence, and iroha trigger execute <id> --args-json ... is available through the sibling CLI.
  • The 2026 DeFi primitive launch uses generic metadata-backed native DeFiInstructionBox records in ../iroha for intents, vaults, operators, AMM hooks, margin, and RWA markets, with SoraSwap product adapters in contracts/{intents,vaults,operators,margin,rwa,dlmm_hooks}.
  • xor#universal is the canonical base asset for routing and pool pricing.
  • docs/parity/migration_register.md is the canonical release ledger. Modules must be ported, blocked, stub, or reference-only; adapted is treated as an intermediate non-release state only.

Layout

  • contracts/ - Kotodama contracts grouped by module.
  • scripts/ - compile, lint, deploy, and smoke wrappers around ../iroha.
  • ui/ - static browser assets for the local contract console.
  • tests/ - end-to-end local verification wrappers that keep the localnet alive for the duration of the run.
  • config/ - local, testnet, and production client templates.
  • docs/ - parity, interface, state-layout, and release notes.
  • artifacts/ - generated bytecode and manifests.
  • deployments/ - deployment evidence, canonical address records, and manifests by environment.

Asset and Naming Policy

  • Base asset: xor#universal
  • Stable basket brand: n3x
  • Helper aliases under this repo: usdt#soraswap.universal, usdc#soraswap.universal, kusd#soraswap.universal, n3x#soraswap.universal

Requirements

  • A sibling ../iroha checkout with ABI v1 synchronous contract-to-contract call_contract support wired through Kotodama codegen, IVM host/runtime dispatch, executor, Torii payload normalization, and CLI helpers.
  • Rust toolchain able to build iroha, ivm, and irohad.
  • curl and jq for Torii smoke calls and response checks.
  • A client config for either local Nexus or a public environment such as Taira testnet.

Commands

make dev-doctor
make dev-build
make dev-check
make dev-test
make dev-schema
make lint
make compile
make simulate-smoke
make simulate-full
make local-up
make deploy-local
make smoke-local
make taira-preflight
make test-local
make test-local-isolated
make test-local-foundation-isolated
make contract-console
make trader-ui
make test-contract-console
make test-contract-console-ui
make test-contract-console-integration
make test-trader-ui
make test-contract-console-live
make test-contract-console-testnet
make soak-contract-console
make deploy-testnet
make deploy-production
make smoke-testnet
make smoke-testnet-readonly
make smoke-production
make smoke-production-readonly
make test-contract-console-production
make testnet-nested-call-probe
make production-nested-call-probe
make test-public-env-helpers
make release-taira
make release-checklist

iroha.contracts.toml is the source of truth for contract sources, aliases, profile client configs, signer/default gas/fee asset settings, test files, and smoke declarations. make lint and make compile are now thin aliases for iroha contract dev check and iroha contract dev build; generated .to, manifest JSON, interface JSON, source maps, and budget reports are emitted under artifacts/compiled/. make dev-schema regenerates the profile/interface summary from the same manifest into docs/interface_specs/generated.md, and make dev-smoke runs the native manifest smoke declarations against the selected profile client config. The SoraSwap wrapper forwards that profile config to the top-level iroha CLI automatically when the file exists, so local doctor/smoke calls use the same signer and Torii endpoint as deploy/smoke flows.

Trigger defaults are conservative for legacy smoke compatibility: product lifecycle callbacks are deployed and configured by bootstrap, but SORASWAP_TRIGGER_LIFECYCLE_ENABLED defaults to 0. Set it to 1 for environments where pre-commit expiry/readiness/liquidation passes should run continuously. Disabled pre-commit declarations are still registered on activation; smoke reports therefore record both registered trigger IDs and active trigger IDs. Range governor, TWAMM, epoch-auction close, and conditional-escrow by-call surfaces are included in the normal smoke evidence, and mutating smoke proves the epoch-auction pre-commit trigger closes and self-disables after its due slot. Trigger-heavy local chains can commit slowly because every registered pre-commit trigger is evaluated each block; local_up.sh therefore raises the generated localnet commit-inflight window and the smoke wrappers expose explicit trigger execute/completion timeouts.

The neighboring ../iroha CLI has first-class lifecycle controls for these gates: iroha trigger list all lists registered triggers, iroha trigger list all --active lists active triggers, and iroha trigger enable <id> / iroha trigger disable <id> toggle the __enabled metadata key. SoraSwap scripts should use soraswap_enable_trigger "$config" <id> / soraswap_disable_trigger "$config" <id> from scripts/common.sh so local and Taira transactions include the required gas metadata.

Simulations

The repo now includes a root Node/TypeScript/Jest workspace for derivatives simulation and cross-product stress runs.

Useful entrypoints:

npm run build
make simulate-smoke
make simulate-full

Simulation suites live under simulations/, and generated telemetry is written to artifacts/telemetry/.

Contract Console

For bridge operations, contract browsing, and ad hoc operator calls, start the local browser console:

make contract-console

By default it serves http://127.0.0.1:4173, reads the live deployments/<env>/*.deploy.json records, refresh-compatible deployments/<env>/contracts.latest.json metadata, plus the adjacent *.manifest.json files, and exposes a local proxy for:

  • POST /v1/contracts/view
  • POST /v1/contracts/call
  • GET /v1/sccp/capabilities
  • GET /v1/sccp/manifests
  • GET /v1/sccp/messages/recent
  • GET /v1/sccp/proofs/message/<message_id>
  • GET /v1/sccp/artifacts/message/<message_id>
  • GET /v1/sccp/jobs/message/<message_id>
  • POST /v1/bridge/proofs/submit
  • POST /v1/bridge/messages
  • GET /v1/pipeline/transactions/status

The backend resolves Torii targets from the checked-in deployment record for the selected environment. Signer configs can contribute authority and signing material, but they do not override the deployment Torii URL. The catalog response now also surfaces signer source metadata and any mismatch warnings that were detected during signer discovery.

Mutation policy is environment-aware:

  • local permits signed mutations by default.
  • testnet public environments, including Taira, permit signed mutations only when the console was started with SORASWAP_ALLOW_TESTNET_MUTATIONS=1.
  • bridge-message submission for proof-managed bridge entrypoints rejects caller-supplied settlement.payload; the release path must stay proof-driven and must be signed by the configured bridge proof authority.

It now also auto-discovers the standard signer configs when they exist and are not placeholder templates:

  • tmp/iroha-localnet/client.toml for local (or $SORASWAP_LOCALNET_DIR/client.toml when that env var is set)
  • config/testnet/taira.client.toml for testnet

The browser UI is deployment-driven: it shows the canonical contract address, dataspace, deploy metadata, and manifest entrypoints already recorded in this repo. No frontend build step is required.

The console now also includes a bridge workspace for the deployed bridge.sccp_bridge contract. It can:

  • aggregate the common bridge view calls (listing_config, mirror_asset, asset_vault_account, route_config, route_provenance, mirror_outbound, inbound_consumed) into one local snapshot request
  • jump directly to the deployed bridge contract in the generic invocation form
  • prefill the common bridge mutation payloads (register_asset, bind_asset_vault, activate_route, activate_route_governed, pause_route, resume_route, lock_to_remote, finalize_inbound)
  • validate bridge action fields before loading them into the generic invocation panel
  • validate lock_to_remote recipients against the live SCCP codec metadata for the selected counterparty lane
  • store browser-local bridge bookmarks for asset keys, routes, transfer ids, and inbound message ids

The operator console now also adds:

  • a transaction tracker that stores recent signed actions in browser localStorage, tracks tx_hash_hex, and polls /v1/pipeline/transactions/status until terminal status
  • best-effort remote transaction history rendering through /v1/transactions/history; public Taira may report this as unavailable, and the UI degrades to a warning state instead of failing
  • an SCCP proof/status workspace that renders live capabilities, manifests, newest-first recent messages, counterparties, verifier targets, finality models, raw bundles, typed artifacts, normalized jobs, and submission-package metadata
  • guided proof and bridge-message submission builders that keep the final payload as editable JSON while prebuilding common message_bundle, finalize_inbound, and activate_route_governed settlement shapes

Trader Cockpit

For swap history, charting, wallet-level PnL, and direct DLMM router trading, start the chart-first trader cockpit:

make trader-ui

By default it serves http://127.0.0.1:4274, reads the same checked-in deployment metadata as the contract console, and proxies a narrow trading surface for:

  • GET /v1/contracts/events
  • GET /v1/contracts/events/sse
  • GET /v1/contracts/rollups/swaps/fills
  • GET /v1/contracts/rollups/swaps/candles
  • GET /v1/contracts/rollups/trader/activity
  • GET /v1/contracts/rollups/trader/account
  • POST /v1/contracts/view
  • POST /v1/contracts/view/batch
  • POST /v1/contracts/call
  • GET /v1/pipeline/transactions/status

The cockpit prefers the deployed dlmm.dlmm_router contract in the selected environment. It loads:

  • trader account rollups for module cards, wallet metrics, and live product posture
  • swap fill and candle rollups for the chart and journal
  • trader activity rollups plus contract-event SSE for the unified action feed and live refresh path
  • batch contract views only for narrow fallback/config reads

The browser surface keeps the chart, journal, avg entry, realized and unrealized PnL, and trader action rails in one frame so users can see position context and submit without bouncing between raw history and a separate form. It also now:

  • keeps a cross-product radar and selectable overview for swaps, n3x, perps, farms, launchpad, options, and cover
  • adds a focused product stage so traders can pin one surface while keeping the rest visible
  • unifies public options into one trader surface instead of split factory/manager tiles
  • exposes real action rails for swaps, n3x, perps, farms, launchpad, options, and cover
  • follows Torii contract-event SSE in live mode and refreshes the cockpit when the chain moves, with automatic polling fallback if the stream drops

It accepts the same signer and authority flags as the contract console:

make trader-ui \
  TRADER_UI_ARGS="--signer local=$SORASWAP_LOCALNET_DIR/client.toml --authority local=$SORASWAP_AUTHORITY"

Custom environments allow signed swaps when a signer with a private key is bound. Public testnet and production environments still inherit the same mutate gate as the contract console, so SORASWAP_ALLOW_TESTNET_MUTATIONS=1 must be exported before starting the trader if you want the submit button enabled against those deployments.

The browser smoke suite starts the real Python trader server against a local mock Torii node and verifies history load, chart/journal rendering, and a live route_swap submission:

make test-trader-ui

Public Taira trader evidence now has dedicated lanes:

make smoke-testnet-trader-readonly
SORASWAP_ALLOW_TESTNET_MUTATIONS=1 make smoke-testnet-trader

Those commands write deployments/testnet/trader_readonly.latest.json and deployments/testnet/trader.latest.json. The readonly lane probes view/batch plus the trader rollups directly. The signed lane also runs a live route_swap probe when the signer can be funded and records the resulting transaction hash and balance deltas.

The trader API route bundle can also be published to SoraFS and addressed through Torii's CID app API gateway:

make publish-trader-api

That writes deployments/testnet/trader_api_bundle.latest.json by default, including the generated content CID, manifest digest, route manifest, the local SoraFS storage-pin receipt, the public pin-registry submission receipt, a read-only deployment-record freshness summary, and a repeated /v1/app-api/cid/{cid} probe summary. The publish path no longer tries to recover stale deployment records by recompiling contracts mid-rollout; it reports drift as deployment_record_check.status = "degraded" and still republishes the route bundle. By default the probe uses the same torii_url as the selected client config; when public rollout is being validated against an explicit direct node, set SORASWAP_TRADER_API_PROBE_ROOT=https://<direct-public-node> before running the target. status = "completed" now means every sampled probe hit 2xx; mixed 200/404 results are reported as status = "inconsistent" so a single lucky cache hit does not look like a healthy public rollout. To activate the CID through an existing public SoraCloud service, set SORASWAP_PUBLISH_TRADER_API_BINDING=1 and SORASWAP_TRADER_API_SERVICE_NAME=<service> before running the target; the script upserts the torii/app_api_binding config with the pinned CID and trader route adapters.

View-only sessions can be started with a default authority override:

make contract-console \
  CONTRACT_CONSOLE_ARGS="--authority testnet=i105..."

Local signed entrypoints stay server-side. Bind an untracked client config to an environment when you want the UI to enable call requests:

make contract-console \
  CONTRACT_CONSOLE_ARGS="--signer local=$SORASWAP_LOCALNET_DIR/client.toml"

For a mutation-enabled Taira session, bind the signer explicitly and enable the mutate gate before starting the console:

export SORASWAP_CLIENT_CONFIG=/absolute/path/to/taira.client.toml
export SORASWAP_ALLOW_TESTNET_MUTATIONS=1
make contract-console \
  CONTRACT_CONSOLE_ARGS="--signer testnet=$SORASWAP_CLIENT_CONFIG --authority testnet=$SORASWAP_AUTHORITY"

If the console port is already occupied, override it with:

make contract-console CONTRACT_CONSOLE_ARGS="--port 4273"

When a signer config includes a public key and the sibling ../iroha/target/debug/iroha binary is present, the console will attempt to derive the canonical I105 authority automatically. Otherwise pass --authority ENV=I105... explicitly.

If you want a strictly manual session, disable default signer discovery with:

make contract-console CONTRACT_CONSOLE_ARGS="--no-auto-signers"

The console backend has a small regression suite:

make test-contract-console

The browser smoke suite serves the static UI, mocks the local proxy surfaces, and verifies catalog load, bridge validation, SCCP discovery, proof lookup rendering, and browser-local persistence:

make test-contract-console-ui

There is also a real browser-to-backend integration smoke. It starts the actual Python console server against a local mock Torii node, then drives the UI through catalog load, bridge snapshot, contract call, SCCP lookup, and proof/message submission flows:

make test-contract-console-integration

If Playwright browser binaries are not installed yet on your machine, run:

npx playwright install chromium

The repo also carries an optional live non-mutating SCCP discovery smoke against the public contract-console surface. It defaults to Taira and stays opt-in so routine local runs do not depend on network reachability:

SORASWAP_RUN_CONTRACT_CONSOLE_LIVE_SMOKE=1 make test-contract-console-live

To point the same smoke at the parallel production environment, set SORASWAP_PUBLIC_ENV=production and either provide an explicit Torii URL or a production client config:

SORASWAP_PUBLIC_ENV=production \
SORASWAP_CONTRACT_CONSOLE_LIVE_TORII_URL=https://production.example.invalid \
SORASWAP_RUN_CONTRACT_CONSOLE_LIVE_SMOKE=1 \
make test-contract-console-live

Signed Taira verification uses the same contract console:

export SORASWAP_CLIENT_CONFIG=/absolute/path/to/taira.client.toml
export SORASWAP_ALLOW_TESTNET_MUTATIONS=1
make test-contract-console-testnet
make soak-contract-console

make test-contract-console-testnet self-grants CanRegisterTrigger to the configured signer when the permission is missing, because the bridge message settlement path uses an ephemeral by-call trigger in the submitted transaction.

make test-contract-console-testnet first auto-discovers the newest unconsumed SORA-targeted bridge transfer for the configured route. When live SCCP discovery is unavailable, the latest saved console evidence already points at a consumed bridge message, or recent live inventory only exposes consumed SORA-targeted transfers, it reuses the newest matching saved console report from deployments/testnet/ or deployments/testnet/archive/ and verifies the duplicate/replay rejection path instead of silently skipping the bridge gate. SORASWAP_TESTNET_BRIDGE_MESSAGE_ID remains available as an explicit debug override when you need to force a specific message id.

Environment Variables

The default contract workflow is profile based. Prefer editing or selecting profiles in iroha.contracts.toml, then run make dev-schema to refresh the generated profile/interface summary. Environment variables are kept for local paths, signer secrets, public rollout gates, and scenario-specific smoke fixtures that should not live in the manifest.

  • SORASWAP_IROHA_ROOT - defaults to ../iroha
  • SORASWAP_PROFILE - selects the iroha.contracts.toml profile used by make dev-*, make lint, and make compile; defaults to local
  • SORASWAP_CONTRACTS_MANIFEST - optional manifest override for wrappers; defaults to iroha.contracts.toml
  • SORASWAP_IROHA_CLI_BIN - optional explicit iroha binary used by scripts/dev_iroha.sh
  • SORASWAP_SKIP_IROHA_DEV_TOOL_BUILD - set to 1 to reuse existing iroha, koto_compile, koto_lint, and koto_test binaries
  • SORASWAP_CLIENT_CONFIG - CLI config path; defaults per script
  • SORASWAP_AUTHORITY - optional canonical I105 override; otherwise derived from the client config public key
  • SORASWAP_BASE_ASSET_ALIAS - defaults to xor#universal
  • SORASWAP_XOR_ASSET_DEFINITION_ID - defaults to Taira's canonical xor#universal asset definition id; used when the public alias is not query-visible
  • SORASWAP_USDT_ASSET_DEFINITION_ID, SORASWAP_USDC_ASSET_DEFINITION_ID, SORASWAP_KUSD_ASSET_DEFINITION_ID, SORASWAP_N3X_ASSET_DEFINITION_ID - optional public helper-asset definition overrides used by bootstrap_assets.sh; set these before make deploy-production when the parallel public chain uses different helper asset ids than Taira
  • SORASWAP_SMOKE_GAS_LIMIT - defaults to 500000
  • SORASWAP_SKIP_IROHA_CLI_BUILD - set to 1 to reuse an existing ../iroha/target/debug/iroha binary even when the sibling tree is newer than the binary
  • SORASWAP_SORAFS_CLI_BIN - optional explicit sorafs_cli path used by make publish-trader-api; otherwise the script reuses or builds ../iroha/target/debug/sorafs_cli
  • SORASWAP_SKIP_KOTO_TOOL_BUILD - set to 1 to reuse existing ../iroha/target/debug/{koto_compile,koto_lint} binaries instead of rebuilding them
  • SORASWAP_SKIP_LOCALNET_TOOL_BUILD - set to 1 to reuse existing ../iroha/target/debug/{iroha,irohad,kagami} binaries instead of rebuilding them
  • SORASWAP_TORII_URL - optional explicit Torii URL override
  • SORASWAP_TESTNET_CHAIN_ID - optional override for the public Taira chain id; when unset, scripts use the copied client config's chain value and fall back to 809574f5-fee7-5e69-bfcf-52451e42d50f
  • SORASWAP_TESTNET_CHAIN_DISCRIMINANT - optional override for the public Taira account-address network prefix; when unset, scripts use [account].chain_discriminant, then [account].profile, then the canonical Taira fallback 369
  • SORASWAP_ALLOW_TESTNET_MUTATIONS - required for any signed Taira console or Taira smoke path
  • SORASWAP_PUBLISH_TRADER_API_BINDING, SORASWAP_TRADER_API_SERVICE_NAME, SORASWAP_TRADER_API_APP_ID, SORASWAP_TORII_API_TOKEN, SORASWAP_TRADER_API_PROBE_ROOT - optional trader API publication controls for make publish-trader-api; binding publication is off by default and requires a live public SoraCloud service name, while SORASWAP_TRADER_API_PROBE_ROOT lets the CID probe hit an explicit direct public validator instead of the client config's default Torii URL
  • SORASWAP_SKIP_PUBLIC_SIGNER_READY_CHECK - optional debug bypass for public deploy/smoke signer balance checks; use only when the configured chain cannot expose the fee asset or faucet state yet and you explicitly want to skip readiness validation
  • SORASWAP_PUBLIC_BOOTSTRAP - optional shared bootstrap toggle for make deploy-testnet and make deploy-production; set to 1 to run the one-time public domain and helper-asset bootstrap before contract deploy
  • SORASWAP_PRODUCTION_BOOTSTRAP - optional production-specific bootstrap toggle that overrides SORASWAP_PUBLIC_BOOTSTRAP for make deploy-production
  • SORASWAP_PRODUCTION_CLIENT_CONFIG - optional default config path used by make deploy-production, make smoke-production, make smoke-production-readonly, and make test-contract-console-production when SORASWAP_CLIENT_CONFIG is not set
  • SORASWAP_PRODUCTION_CHAIN_ID - optional production chain-id override used when the production client config is copied from another environment or otherwise carries the wrong chain value
  • SORASWAP_PRODUCTION_CHAIN_DISCRIMINANT - optional network-prefix override for the parallel production environment; falls back to SORASWAP_CHAIN_DISCRIMINANT when omitted
  • SORASWAP_LOCAL_FEE_ASSET_DEFINITION_ID, SORASWAP_TESTNET_FEE_ASSET_DEFINITION_ID - fee-asset definition ids inserted into ledger transaction metadata for local/testnet bootstrap commands and public contract-call gas metadata; testnet gas metadata defaults to the canonical definition id because xor#universal is not guaranteed to be an active public gas alias
  • SORASWAP_TESTNET_FEE_ASSET_LABEL - optional testnet gas metadata override; defaults to SORASWAP_TESTNET_FEE_ASSET_DEFINITION_ID
  • SORASWAP_PRODUCTION_FEE_ASSET_DEFINITION_ID, SORASWAP_PRODUCTION_FEE_ASSET_LABEL - optional production fee-asset overrides for deploy/bootstrap/smoke preflight when the production fee asset is not query-visible through SORASWAP_FEE_ASSET_ALIAS
  • SORASWAP_LEDGER_GAS_LIMIT - optional gas limit for metadata-backed ledger/SNS bootstrap transactions; defaults to 2000000
  • SORASWAP_PUBLIC_RUN_SUFFIX, SORASWAP_PUBLIC_BRIDGE_ROUTE, SORASWAP_PUBLIC_BRIDGE_RECENT_LIMIT, SORASWAP_PUBLIC_BRIDGE_MESSAGE_ID - optional shared public-env overrides used by the generic public smoke and contract-console wrappers before their built-in defaults
  • SORASWAP_TESTNET_BRIDGE_MESSAGE_ID - optional debug override for make test-contract-console-testnet when you want to force a specific live SCCP message id instead of using chain-derived recent-message discovery
  • SORASWAP_TESTNET_BRIDGE_ROUTE - optional bridge route override for testnet console smoke when the looked-up message bundle cannot derive the route
  • SORASWAP_TESTNET_RUN_SUFFIX - optional suffix reused by the signed Taira smoke for mutable launchpad, referral, farm, perps, options, cover, and automation identifiers
  • SORASWAP_PRODUCTION_BRIDGE_MESSAGE_ID, SORASWAP_PRODUCTION_BRIDGE_ROUTE, SORASWAP_PRODUCTION_BRIDGE_RECENT_LIMIT, SORASWAP_PRODUCTION_RUN_SUFFIX - optional production-wrapper equivalents used by the parallel deployments/production evidence family
  • SORASWAP_PUBLIC_XOR_TOPUP_MAX_ATTEMPTS, SORASWAP_PUBLIC_XOR_TOPUP_MAX_USDT_IN, SORASWAP_PUBLIC_XOR_TOPUP_BUFFER - optional shared public-env signer autofund controls used by the mutating public smoke before its built-in defaults
  • SORASWAP_TESTNET_XOR_TOPUP_MAX_ATTEMPTS, SORASWAP_TESTNET_XOR_TOPUP_MAX_USDT_IN, SORASWAP_TESTNET_XOR_TOPUP_BUFFER - optional testnet signer autofund controls for the mutating public smoke
  • SORASWAP_PRODUCTION_XOR_TOPUP_MAX_ATTEMPTS, SORASWAP_PRODUCTION_XOR_TOPUP_MAX_USDT_IN, SORASWAP_PRODUCTION_XOR_TOPUP_BUFFER - optional production-wrapper equivalents used by make smoke-production
  • SORASWAP_LAUNCHPAD_SALE_ASSET_ID - optional launchpad sale-asset override; local and signed Taira launchpad smoke default to usdt#soraswap.universal so the executor seeds the canonical xor/usdt DLMM pool
  • SORASWAP_LAUNCHPAD_POOL_QUOTE_ASSET_ID - optional launchpad executor / DLMM quote-asset override; defaults to usdt#soraswap.universal
  • SORASWAP_RECOMMENDED_TX_GOSSIP_FRAME_CAP - defaults to 1048576; deploy scripts warn when live Taira is below this frame-cap budget
  • SORASWAP_CONTRACT_DEPLOY_MAX_TIME_SECS - defaults to 45; max request time for the public /v1/contracts/deploy wrapper before deploy recovery/fallback logic takes over
  • SORASWAP_CONTRACT_APP_DEPLOY_MAX_TIME_SECS - defaults to 3600; max request time for the multi-contract contract app deploy bundle path before the local/public deploy wrapper gives up
  • SORASWAP_CONTRACT_APP_ACTIVATION_MAX_TIME_SECS - defaults to 180; max wait for each bundle alias to resolve to its planned contract address before materializing deployment evidence
  • SORASWAP_CONTRACT_APP_ACTIVATION_TICK_BLOCKS, SORASWAP_CONTRACT_APP_ACTIVATION_TICK_INTERVAL_SECS - local activation waits can submit no-wait ping ticks to advance block-height-gated activation; ticks are disabled on public configs and throttled to every 10 seconds by default to avoid flooding a stalled local queue
  • SORASWAP_DEPLOY_PIPELINE_WAIT_SECS, SORASWAP_DEPLOY_COMMITTED_WAIT_SECS, SORASWAP_DEPLOY_MANIFEST_WAIT_SECS, SORASWAP_DEPLOY_NONCE_WAIT_SECS - default to 300, 120, 180, and 30; control live deploy revalidation windows for pipeline status, committed transaction lookup, manifest visibility, and deploy-nonce visibility during deploy recovery plus post-deploy bootstrap
  • SORASWAP_CONTRACT_CALL_MAX_TIME_SECS - defaults to 120; max request time for signed /v1/contracts/call mutations before the wrapper fails the request
  • SORASWAP_CONTRACT_CALL_RETRY_COUNT - defaults to 1; mutating /v1/contracts/call requests are not retried by default because a transport timeout can still submit the first transaction and make a blind retry duplicate a non-idempotent action
  • SORASWAP_ACCEPT_PIPELINE_APPLIED_WITHOUT_COMMITTED_TX - defaults to auto; public environments accept terminal pipeline Applied|Committed when committed transaction lookup cannot decode the public response, while local environments remain strict unless overridden
  • SORASWAP_PIPELINE_APPLIED_COMMITTED_VERIFY_SECS - defaults to 5; short committed-transaction decode attempt before the public pipeline-only fallback is used
  • SORASWAP_CONTRACT_VIEW_MAX_TIME_SECS, SORASWAP_TORII_READ_MAX_TIME_SECS - optional public-node timeout controls for /v1/contracts/view and read-only Torii queries; useful when taira.sora.org is intermittently resetting or stalling connections
  • SORASWAP_TRIGGER_EXECUTE_TIMEOUT_MS, SORASWAP_TRIGGER_EXECUTE_POLL_INTERVAL_MS - optional by-call trigger execution wait controls for iroha trigger execute; defaults are SORASWAP_TX_COMMITTED_WAIT_SECS * 1000 and 1000
  • SORASWAP_TRIGGER_COMPLETION_TIMEOUT_MS, SORASWAP_TRIGGER_COMPLETION_CAPTURE_WARMUP_SECONDS, SORASWAP_TRIGGER_COMPLETION_PROBE_MS, SORASWAP_TRIGGER_COMPLETION_PROBE_LIMIT - optional trigger completion evidence controls used by local/public smoke and readonly public probes
  • SORASWAP_EPOCH_AUCTION_CLOSE_WAIT_ATTEMPTS - optional mutating-smoke wait budget for proving the epoch-auction pre-commit trigger closes the current epoch and self-disables after epoch_end_slot
  • SORASWAP_LOCALNET_DIR - optional override for the generated localnet directory
  • SORASWAP_LOCALNET_BASE_API_PORT - optional localnet API port root override; useful when another local Nexus already occupies 8080-8082
  • SORASWAP_LOCALNET_BASE_P2P_PORT - optional localnet P2P port root override; useful when another local Nexus already occupies 1337+
  • SORASWAP_LOCALNET_CONSENSUS_MODE - optional localnet consensus override; defaults to npos for local_up.sh and permissioned for tests/isolated_e2e.sh
  • SORASWAP_LOCALNET_BLOCK_TIME_MS, SORASWAP_LOCALNET_COMMIT_TIME_MS - optional Kagami timing overrides passed through by local_up.sh; the isolated local smoke leaves them unset by default so Kagami's fast localnet defaults are used
  • SORASWAP_LOCALNET_COMMIT_INFLIGHT_TIMEOUT_MS - optional override for [sumeragi.persistence].commit_inflight_timeout_ms in generated local peer configs; SoraSwap defaults it to 120000 so cold DLMM deploy and trigger-heavy pre-commit blocks do not stall behind Kagami's tighter localnet cap
  • SORASWAP_WARM_VIEW_TIMEOUT_SECS - optional per-view timeout used only by bootstrap prewarm calls; defaults to 5 so a cold diagnostic view cannot stall the whole isolated bootstrap
  • SORASWAP_LOCALNET_GUEST_STACK_BYTES - optional localnet guest stack override; defaults to 8388608 so DLMM swap smoke has an 8 MiB guest stack budget
  • SORASWAP_LOCALNET_GAS_TO_STACK_MULTIPLIER - optional localnet gas-to-stack multiplier override; defaults to 8 so the DLMM pool can use the raised guest stack budget at its current max_cycles
  • SORASWAP_LOCALNET_MEMORY_BUDGET_PROFILE - optional localnet IVM memory-budget profile name; defaults to soraswap-dlmm
  • SORASWAP_LOCALNET_MAX_STACK_BYTES - optional localnet compute-profile stack cap override; defaults to the same value as SORASWAP_LOCALNET_GUEST_STACK_BYTES
  • SORASWAP_INIT_CONTRACT_STATE - defaults to 1 on testnet deploys; set to 0 only for an explicit debug bypass of post-deploy init
  • SORASWAP_BOOTSTRAP_SCOPE - defaults to full; set to foundation to stop post-deploy initialization after n3x plus DLMM setup
  • SORASWAP_SMOKE_SCOPE - defaults to full; set to foundation to skip launchpad, referral, farms, perps, options, cover, and automation smoke mutations
  • SORASWAP_SMOKE_BLOCK_WAIT_ATTEMPTS, SORASWAP_SMOKE_BLOCK_WAIT_TICK - local smoke block-height wait controls; defaults are 900 attempts and 1 ping tick per unchanged observed height so trigger-heavy pre-commit flows can advance gated slots without an external transaction source
  • SORASWAP_TREASURY_ACCOUNT - optional override for the treasury/vault account used during post-deploy init
  • SORASWAP_BRIDGE_PROOF_AUTHORITY - optional bridge proof authority; bootstrap defaults it to the deployment authority and enforces it through bridge_authorities()
  • SORASWAP_ORACLE_PUBLIC_KEY_HEX - optional override for the bootstrap and smoke oracle public key; raw 32-byte Ed25519 public keys and Iroha ed0120... public keys are accepted and normalized before contract init, and public configs default to the client config signer when this is unset
  • SORASWAP_ORACLE_PRIVATE_KEY_HEX - optional override for scripts/oracle_payload.py; raw seed, seed+public, and Iroha 802620... private keys are accepted, and public configs default to the client config signer when this is unset
  • SORASWAP_ORACLE_SCHEME - defaults to 1 for Ed25519 signatures over the exact raw UTF-8 JSON oracle payload bytes
  • SORASWAP_POOL_SEED_NEXT_BASE, SORASWAP_POOL_SEED_NEXT_QUOTE, SORASWAP_POOL_SEED_FAR_BASE, SORASWAP_POOL_SEED_FAR_QUOTE - optional adjacent-bin bootstrap liquidity overrides
  • SORASWAP_POOL_POSITION_ID, SORASWAP_POOL_POSITION_BASE, SORASWAP_POOL_POSITION_QUOTE, SORASWAP_POOL_POSITION_REMOVE_SHARES - optional local DLMM smoke position controls
  • SORASWAP_POOL_IMPACT_CAP_BPS, SORASWAP_POOL_MIN_RESERVE_BASE, SORASWAP_POOL_MIN_RESERVE_QUOTE, SORASWAP_POOL_MAX_BINS_PER_SWAP, SORASWAP_POOL_BIN_LIQUIDITY_CAP - optional DLMM risk guard overrides
  • SORASWAP_POOL_SMOKE_SWAP_IN - local DLMM swap input used by smoke flows
  • SORASWAP_ROUTER_BIN_QUOTE_IN - router quote_bin sample amount used by smoke flows
  • SORASWAP_N3X_VAULT_ACCOUNT, SORASWAP_DLMM_POOL_VAULT_ACCOUNT - optional custody-account overrides for bootstrap repair and custom environments; bootstrap now targets the current deployed contract subjects by default and, on public testnet|production, migrates seeded balances forward from previous contract-subject custody when contracts are upgraded
  • SORASWAP_N3X_SMOKE_USDT_IN, SORASWAP_N3X_SMOKE_USDC_IN, SORASWAP_N3X_SMOKE_KUSD_IN, SORASWAP_N3X_TARGET_USDT_BPS, SORASWAP_N3X_TARGET_USDC_BPS, SORASWAP_N3X_TARGET_KUSD_BPS, SORASWAP_N3X_MINT_FEE_BPS, SORASWAP_N3X_REDEEM_FEE_BPS - optional n3x smoke controls for basket inputs, target weights, and fee configuration
  • SORASWAP_SALE_NAME, SORASWAP_LAUNCHPAD_SMOKE_PAYMENT_AMOUNT, SORASWAP_LAUNCHPAD_SMOKE_ALLOCATION_ID, SORASWAP_LAUNCHPAD_CLAIM_INVENTORY_AMOUNT, SORASWAP_LAUNCHPAD_CLAIM_SLOT, SORASWAP_LAUNCHPAD_SEED_PAYMENT_AMOUNT, SORASWAP_LAUNCHPAD_SEED_SALE_AMOUNT, SORASWAP_LAUNCHPAD_SEED_BIN_ID, SORASWAP_LAUNCHPAD_SEED_POSITION_ID, SORASWAP_REFUND_SALE_NAME, SORASWAP_REFUND_ALLOCATION_ID, SORASWAP_REFUND_PAYMENT_AMOUNT, SORASWAP_REFUND_SOFT_CAP - optional launchpad smoke controls for recorded allocations, claim inventory, refunds, and the explicit DLMM seed plan
  • SORASWAP_REFERRAL_SMOKE_MEMBER, SORASWAP_REFERRAL_SMOKE_PARENT_MEMBER, SORASWAP_REFERRAL_SMOKE_CLAIM_THRESHOLD, SORASWAP_REFERRAL_SMOKE_ACCRUAL, SORASWAP_REFERRAL_SMOKE_DIRECT_SHARE_BPS, SORASWAP_REFERRAL_SMOKE_PARENT_SHARE_BPS - optional referral smoke controls for the routed child and parent member settlement path
  • SORASWAP_FARM_SMOKE_REWARD_FUND, SORASWAP_FARM_SMOKE_STAKE_AMOUNT, SORASWAP_FARM_SMOKE_UNSTAKE_AMOUNT, SORASWAP_FARM_SMOKE_CLAIM_SLOT, SORASWAP_FARM_SMOKE_UNSTAKE_SLOT - optional farms smoke controls for the slot-synced accrual path
  • SORASWAP_INTENT_SMOKE_DEADLINE_SLOT, SORASWAP_INTENT_SMOKE_DEADLINE_OFFSET_SLOTS, SORASWAP_VAULT_SMOKE_CLAIM_SLOT, SORASWAP_VAULT_SMOKE_CLAIM_DELAY_SLOTS - optional intent and vault smoke timing controls; defaults are derived from current chain height because fills and redemption claims use contract block_height()
  • SORASWAP_PERPS_SMOKE_FUNDING_BPS, SORASWAP_PERPS_SMOKE_MAX_LEVERAGE_BPS, SORASWAP_PERPS_SMOKE_MAINTENANCE_MARGIN_BPS, SORASWAP_PERPS_SMOKE_LIQUIDATION_FEE_BPS - optional perps bootstrap defaults for market funding and guard configuration
  • SORASWAP_PERPS_MARKET_OPEN_INTEREST_CAP, SORASWAP_PERPS_MARKET_FUNDING_INTERVAL_SLOTS, SORASWAP_PERPS_MARKET_ORACLE_STALE_SLOTS, SORASWAP_PERPS_MARKET_BACKLOG_LIMIT, SORASWAP_PERPS_MARKET_UTILISATION_CLAMP_BPS, SORASWAP_PERPS_MARKET_LIQUIDATION_STRESS_LIMIT - optional perps market registration overrides for the shared derivatives stack
  • SORASWAP_PERPS_SMOKE_POSITION, SORASWAP_PERPS_SMOKE_SIZE, SORASWAP_PERPS_SMOKE_COLLATERAL, SORASWAP_PERPS_SMOKE_ADD_COLLATERAL, SORASWAP_PERPS_SMOKE_REMOVE_COLLATERAL, SORASWAP_PERPS_SMOKE_REQUESTED_LEVERAGE_BPS, SORASWAP_PERPS_SMOKE_LIQUIDATION_REQUESTED_LEVERAGE_BPS, SORASWAP_PERPS_SMOKE_ENTRY_PRICE_BPS, SORASWAP_PERPS_SMOKE_FUNDING_MARK_PRICE_BPS, SORASWAP_PERPS_SMOKE_FUNDING_INDEX_PRICE_BPS, SORASWAP_PERPS_SMOKE_EXIT_MARK_PRICE_BPS, SORASWAP_PERPS_SMOKE_LIQUIDATION_COLLATERAL, SORASWAP_PERPS_SMOKE_LIQUIDATION_STRESS_MARK_PRICE_BPS, SORASWAP_PERPS_SMOKE_LIQUIDATION_HEALTHY_MARK_PRICE_BPS, SORASWAP_PERPS_SMOKE_LIQUIDATION_SCAN_LIMIT - optional perps smoke controls for the normal open/funding/margin/close path plus the automatic queue/recover/liquidate rehearsal; the liquidation path uses its own requested leverage so lower-margin liquidation fixtures can stay valid against the market max leverage check
  • SORASWAP_OPTIONS_SHOUT_TENOR_SLOTS, SORASWAP_OPTIONS_OUTPERFORMANCE_TENOR_SLOTS, SORASWAP_OPTIONS_SHOUT_STRIKE_BPS, SORASWAP_OPTIONS_OUTPERFORMANCE_STRIKE_BPS, SORASWAP_OPTIONS_COLLATERAL_MULTIPLIER_BPS, SORASWAP_OPTIONS_SHOUT_BASE_PREMIUM_BPS, SORASWAP_OPTIONS_OUTPERFORMANCE_BASE_PREMIUM_BPS, SORASWAP_OPTIONS_SHOUT_EXPIRY_SLOT, SORASWAP_OPTIONS_OUTPERFORMANCE_EXPIRY_SLOT, SORASWAP_OPTIONS_SHOUT_MAX_NOTIONAL, SORASWAP_OPTIONS_OUTPERFORMANCE_MAX_NOTIONAL - optional options template and series bootstrap overrides
  • SORASWAP_OPTIONS_GUARD_BUMP_ACTIVATE_BPS, SORASWAP_OPTIONS_GUARD_BUMP_DEACTIVATE_BPS, SORASWAP_OPTIONS_GUARD_PAUSE_THRESHOLD_BPS, SORASWAP_OPTIONS_GUARD_BUMP_PERCENT_BPS - optional options factory utilisation-guard overrides
  • SORASWAP_OPTIONS_SHOUT_SMOKE_NOTIONAL, SORASWAP_OPTIONS_SHOUT_SMOKE_PREMIUM_PAID, SORASWAP_OPTIONS_SHOUT_SMOKE_COLLATERAL_LOCKED, SORASWAP_OPTIONS_SHOUT_SMOKE_RECORD_MARK_BPS, SORASWAP_OPTIONS_SHOUT_SMOKE_EXERCISE_MARK_BPS, SORASWAP_OPTIONS_OUTPERFORMANCE_SMOKE_NOTIONAL, SORASWAP_OPTIONS_OUTPERFORMANCE_SMOKE_PREMIUM_PAID, SORASWAP_OPTIONS_OUTPERFORMANCE_SMOKE_COLLATERAL_LOCKED, SORASWAP_OPTIONS_OUTPERFORMANCE_FINAL_MARK_BPS, SORASWAP_OPTIONS_OUTPERFORMANCE_FINAL_QUOTE_MARK_BPS - optional local active options smoke controls for shout and outperformance buy/settle/exercise flows
  • SORASWAP_COVER_REQUIRED_OBSERVATIONS, SORASWAP_COVER_ORACLE_STALE_SLOTS, SORASWAP_COVER_SMOKE_NOTIONAL, SORASWAP_COVER_SMOKE_PAYOUT_AMOUNT, SORASWAP_COVER_SMOKE_PREMIUM_PAID, SORASWAP_COVER_SMOKE_LOWER_BOUND, SORASWAP_COVER_SMOKE_UPPER_BOUND, SORASWAP_COVER_SMOKE_TRIGGER_PRICE, SORASWAP_COVER_SMOKE_WINDOW_SLOTS, SORASWAP_COVER_SMOKE_POLICY_REQUIRED_OBSERVATIONS - optional cover bootstrap and active local smoke controls, including the degraded-oracle reset drill
  • SORASWAP_RISK_BUCKET_1_BOOTSTRAP_DEPOSIT, SORASWAP_RISK_BUCKET_2_BOOTSTRAP_DEPOSIT, SORASWAP_RISK_BUCKET_3_BOOTSTRAP_DEPOSIT - optional shared risk-vault bootstrap funding overrides for buckets 1=perps, 2=options, 3=cover; the signed Taira flow now seeds bucket 1 with 200 by default so the live perps smoke uses the same funded baseline as the local rehearsal
  • SORASWAP_AUTOMATION_SMOKE_JOB, SORASWAP_AUTOMATION_SMOKE_EXECUTOR, SORASWAP_AUTOMATION_SMOKE_NEXT_SLOT, SORASWAP_AUTOMATION_SMOKE_RESUME_SLOT, SORASWAP_AUTOMATION_SMOKE_RETRY_DELAY_SLOTS, SORASWAP_AUTOMATION_SMOKE_MAX_RETRIES, SORASWAP_AUTOMATION_SMOKE_CRON_INTERVAL_SLOTS - optional automation smoke scheduler overrides

Local Nexus

scripts/local_up.sh generates and starts a fresh one-peer Kagami localnet in tmp/iroha-localnet using the sibling ../iroha checkout and the Nexus/NPoS profile. It now also injects a SoraSwap-specific IVM stack profile into the generated peer config so DLMM swap smoke runs with an 8 MiB guest stack budget by default, and raises the generated sumeragi.persistence.commit_inflight_timeout_ms to 120000 so cold large-contract deploy and trigger-heavy pre-commit blocks do not flap at the default localnet cap. When another local Nexus is already running, set SORASWAP_LOCALNET_DIR, SORASWAP_LOCALNET_BASE_API_PORT, and SORASWAP_LOCALNET_BASE_P2P_PORT to spin up an isolated verification localnet instead of reusing the default one.

Default local client config:

tmp/iroha-localnet/client.toml

Local bootstrap also acquires the soraswap SNS domain-name lease before registering the on-ledger soraswap domain, which is now required by current Nexus core. It then binds and tops up xor#universal as the base asset alongside the repo helper assets.

iroha.contracts.toml is the repo's canonical SoraSwap bundle manifest. make deploy-local compiles the listed contracts through iroha contract dev build, then hands the full bundle to ../iroha via iroha contract app deploy --manifest iroha.contracts.toml so address planning, alias binding, deploy receipts, and recovery semantics live in the platform instead of repo shell logic. The wrapper still runs scripts/bootstrap_contract_state.sh after activation so the foundational contracts have usable local state before smoke calls. Full bootstrap requires an oracle public key, initializes derivatives with the configured signer, binds the bridge proof authority, and verifies those singleton settings through typed views. The bootstrap is skip-and-verify: singleton init/config writes are skipped when their typed config views already match, and the DLMM seed block is only replayed when the current bin and position snapshots are still pristine. Each deploy now writes both the platform bundle receipt to deployments/local/soraswap.bundle.deploy.json and the materialized per-contract deployments/local/<contract>.deploy.json evidence used by the smoke/bootstrap flows, plus a timestamped deployments/local/contracts.<utc>.json snapshot of the whole local deployment set.

make dev-smoke first checks that generated artifacts are not stale, then runs the declarative [[smoke]] views/calls from iroha.contracts.toml through iroha contract dev smoke; it requires the selected profile client config, so run make local-up before using the default local profile. make smoke-local remains the domain-heavy integration rehearsal and writes a machine-readable report to deployments/local/smoke.latest.json plus a timestamped copy. That report separates committed mutation transaction hashes from typed /v1/contracts/view results, records registered/active trigger evidence plus by-call completion evidence, and records decoded integer snapshots for the n3x, deployable DLMM, launchpad, referral, farms, risk vault, perps, options, cover, and automation surfaces. The n3x section includes basket backing plus per-asset fee reserves, the launchpad section includes both sale-level claim/seed aggregates plus allocation refund state, and the referral section includes routed child-plus-parent settlement state. The derivatives section now signs raw UTF-8 JSON oracle payloads with SORASWAP_ORACLE_PRIVATE_KEY_HEX, uses contract block_height() for price-sensitive current-slot checks, and includes committed local write-path coverage for perps open/funding/margin/close plus queue/recover/requeue/liquidate, shout buy/record/exercise, outperformance buy/series settlement/exercise, and cover register/degraded-reset/claim, all routed through risk_vault.

Public Testnet

The public testnet template lives at:

config/testnet/taira.client.toml.example

Copy it to an untracked .toml, set the correct credentials, then point SORASWAP_CLIENT_CONFIG at that file before running make deploy-testnet. Use a fully qualified account domain in the copied config, for example wonderland.universal.

Use the read-only preflight before the signed release gate when setting up a workstation or diagnosing public Taira:

make taira-preflight

It writes deployments/testnet/preflight.latest.json, checks client-config shape, mutation consent, oracle key availability, public endpoint reachability, current block height, live block-1 chain fingerprint, native Torii MCP status, faucet puzzle availability, signer derivation/funding when a real config is present, existing release evidence, and any current-chain nested-call probe blocker. When SORASWAP_ORACLE_PUBLIC_KEY_HEX and SORASWAP_ORACLE_PRIVATE_KEY_HEX are unset, the Taira client config signer is used as the native oracle provider. It blocks the full release when native Torii MCP is missing or unhealthy; the CLI/HTTP scripts remain useful for diagnostics, but not for claiming release readiness. It does not deploy contracts or print signing secrets.

As verified on May 27, 2026, the operator host behind taira.sora.org may be running an existing Sora-prefix localnet state with chain id 00000000-0000-0000-0000-000000000000 and account prefix 753, while the canonical Taira template remains chain id 809574f5-fee7-5e69-bfcf-52451e42d50f with prefix 369. Keep the copied, untracked client config aligned with the live host before running deploy or smoke flows; use chain = "00000000-0000-0000-0000-000000000000" plus [account].chain_discriminant = 753 for that localnet state, or restore the canonical template values after a fresh Taira redeploy.

make deploy-testnet now treats public deployment as a permissionless universal dataspace bundle flow. Before deploying it fingerprints the live chain using chain id + block 1 hash, writes deployments/testnet/chain.latest.json, and archives stale deployments/testnet evidence under deployments/testnet/archive/<utc>-<block1-hash>/ whenever Taira has been redeployed without changing the chain id. The observed torii_url is still recorded in that snapshot as metadata, but endpoint URL is not part of chain identity. The wrapper auto-runs the helper domain/asset bootstrap when soraswap.universal or the helper aliases are missing, compiles iroha.contracts.toml, submits it through iroha contract app deploy, persists the first-class platform receipt to deployments/testnet/soraswap.bundle.deploy.json, then materializes the per-contract *.deploy.json records that the readonly and mutable smoke flows already consume. deployments/testnet/nested_call_probe.latest.json records persisted bytes state round-trip, minimal no-arg live call_contract(...), and multi-hop nested AssetOps relay checks that must pass before bootstrap proceeds.

scripts/fund_testnet_signer.sh is the operator helper for public Taira funding. make deploy-testnet will auto-claim faucet funds when the signer is missing or unfunded, solve the faucet PoW puzzle, and wait for a positive xor#universal balance before deploying. Post-deploy init now runs by default there, and SORASWAP_BOOTSTRAP_SCOPE=foundation|full still narrows the init surface when needed.

Public bootstrap now targets the current n3x_hub and DLMM pool contract subjects on testnet|production and migrates seeded balances forward from previous contract-subject custody after upgrades. local still defaults n3x custody to the n3x_hub contract subject, and SORASWAP_N3X_VAULT_ACCOUNT remains the explicit override when an operator wants to force a different custody account during repair or migration drills.

make smoke-testnet is now the canonical signed Taira rehearsal for the mutable DeFi surface. It requires SORASWAP_ALLOW_TESTNET_MUTATIONS=1, reuses the readonly compatibility lane for deployment-record and manifest revalidation, rechecks the saved nested_call_probe.latest.json evidence against the current chain, signs oracle payloads when derivative write paths are enabled, then executes the same active router, launchpad, farms, automation, and derivatives write paths that the local smoke uses, including the perps queue/recover/requeue/liquidate path, before writing deployments/testnet/smoke.latest.json.

The bridge proof lane stays in the same release gate, but it runs as its own target: make test-contract-console-testnet records deployments/testnet/contract_console_smoke.latest.json separately so the bridge message is not consumed twice by a single rehearsal. A green release gate therefore requires both the signed make smoke-testnet evidence and the signed make test-contract-console-testnet evidence.

make smoke-testnet-readonly preserves the older non-destructive compatibility lane. It revalidates each saved *.deploy.json record on the current chain, rebuilds missing records from live aliases plus local manifests when possible, compares live code manifests against any saved deployment manifests, and records typed readonly view evidence under the same deployments/testnet/ directory.

make release-taira is the full public release runner. It requires a real untracked config/testnet/taira.client.toml or SORASWAP_CLIENT_CONFIG, rejects the checked-in example and placeholder credentials, and requires SORASWAP_ALLOW_TESTNET_MUTATIONS=1 before any public mutation. By default, the same client config signer submits native oracle attestations; set SORASWAP_ORACLE_PUBLIC_KEY_HEX plus SORASWAP_ORACLE_PRIVATE_KEY_HEX only when overriding that provider. It runs the release sequence in order: read-only preflight, nested-call probe, deploy, readonly smoke, mutating smoke, contract-console smoke, trader readonly, trader mutating, trader API publish, and release-checklist.

deployments/testnet/rwa_compliance.latest.json is a required release artifact. The repo validates the evidence hook only; issuer approval, legal review, compliance policy, NAV source, and redemption terms remain external artifacts referenced by non-empty ids or URLs in that JSON.

The release flow no longer depends on a separate staging environment. The repo now also carries a parallel production wrapper family:

make deploy-production
make smoke-production
make smoke-production-readonly
make production-nested-call-probe
make test-contract-console-production

Those commands write the same artifact shape under deployments/production/, reuse the same signed public-env code path as Taira, and keep the same SORASWAP_ALLOW_TESTNET_MUTATIONS=1 mutation gate for the mutable smoke and console paths. Production wrappers default SORASWAP_CLIENT_CONFIG from SORASWAP_PRODUCTION_CLIENT_CONFIG or config/production/production.client.toml when present.

When the production client config is copied from another chain or the production fee asset is not query-visible by alias, set SORASWAP_PRODUCTION_CHAIN_ID, SORASWAP_PRODUCTION_CHAIN_DISCRIMINANT, and SORASWAP_PRODUCTION_FEE_ASSET_DEFINITION_ID before running the production wrappers so contract-subject derivation and fee-balance preflight stay pinned to the real production chain.

Release guidance and operator procedures live under:

On March 28, 2026, probing the live Taira node showed:

  • chain id 809574f5-fee7-5e69-bfcf-52451e42d50f
  • /v1/accounts/onboard responding 403 with UAID onboarding disabled
  • /v1/accounts/faucet/puzzle responding 200 once faucet is enabled on the public node
  • status.tx_gossip.caps.frame_cap_bytes is expected to be at least 1048576 for routine SoraSwap deploys without split fallback
  • public contract lifecycle writes were being rejected when Taira omitted an explicit [nexus.fees] block and fell back to the canonical default fee selector instead of xor#universal

On April 15, 2026, probing the live Taira node additionally showed:

  • /v1/contracts/rollups/swaps/fills, /v1/contracts/rollups/swaps/candles, /v1/contracts/rollups/trader/activity, and /v1/contracts/rollups/trader/account still responding 404 Not Found
  • /v1/contracts/view/batch still responding 404 Not Found
  • fresh public faucet claims for new testnet signers reaching terminal Expired under the saturated public queue, so the trader signed evidence lane now retries the faucet claim and records the exact blocker in deployments/testnet/trader.latest.json when the public node still cannot fund a brand-new signer in time

Public SoraSwap docs and scripts now target canonical contract addresses in the universal dataspace. A Taira rollout must therefore include both the explicit nexus.fees.fee_asset_id = "xor#universal" override and the raised network.max_frame_bytes_tx_gossip = 1048576 setting from ../iroha/configs/soranexus/taira/config.toml, then a fresh make deploy-testnet run after the node comes back.

On May 23, 2026, the live Taira probe initially showed native Torii MCP returning 404; make taira-preflight treats that as a release blocker before any signed live action. The public peers were then restarted with [torii.mcp] enabled, non-universal dataspace manifest_hash values, and a fresh ../iroha irohad build. A later probe reported mcp_http_status = "200" and nested_call_probe.supported = true. The release gate now defaults the native oracle provider to the Taira client config signer, so separate oracle env vars are only required when an operator wants a different provider keypair.

When deployments/testnet/preflight.latest.json reports mcp_http_status = "404" or any non-200 MCP status, stop before signed live actions. When deployments/testnet/nested_call_probe.latest.json reports state_bytes_roundtrip_supported = true but either nested_call_supported = false or nested_asset_ops_supported = false, first check the probe's probe_asset.asset_definition_id; if that id is wrong for the live chain, fix the asset wiring. If the asset id is correct, treat it as the public Taira runtime rejecting a required nested contract/AssetOps capability. The runtime fix path is to roll public Taira forward from ../iroha, not to add a non-nested fallback here:

  • build and stage an exact runtime bundle with bash ../iroha/configs/soranexus/taira/build_taira_rollout_bundle.sh
  • install/restart the public validator(s) from that bundle
  • verify the sibling runtime canary with cargo test -p iroha_core --lib contract_call_transaction_preserves_three_hop_transfer_authorities -- --nocapture
  • rerun the public canary plus the SoraSwap gate with bash ../iroha/configs/soranexus/taira/verify_soraswap_rollout.sh --public-root "<direct-public-node>" --write-config /run/secrets/taira-canary-client.toml --soraswap-client-config /absolute/path/to/taira.client.toml --run-release-checklist --allow-testnet-mutations

For a collision-free local full-stack check, use make test-local-isolated. It starts a dedicated localnet under tmp/iroha-localnet-verify, defaults to 18080 / 11337 instead of the main local ports, deploys the full contract set, runs the full smoke_local.sh mutation flow against the generated client config, asserts the exact post-smoke n3x and DLMM view snapshots, and drives the shared derivatives write path through risk_vault before tearing the node back down. The same DLMM-oriented stack overrides are applied there by default, and the isolated permissioned wrapper now raises both Kagami timing knobs to 5000 ms by default so the cold first-write dlmm_pool path stays clear of the 6 s quorum-timeout band seen on the debug localnet profile.

For a foundation-only deployability check, use make test-local-foundation-isolated. It exports both scope variables as foundation, proves the n3x plus DLMM bootstrap and smoke path on a dedicated permissioned localnet, and skips later-module initialization so unrelated launchpad/farms/perps/options scaffolds do not block DLMM verification.

Notes

  • The scripts are idempotent where practical and explicitly verify alias bindings before skipping asset registration.
  • Bootstrap now applies the init-only n3x, DLMM, launchpad, referral, farms, risk-vault, perps, options, and cover config surfaces before smoke begins. The derivatives bootstrap also binds the product contracts into the shared risk_vault controller map so all later perps/options/cover write paths route through bucket accounting instead of raw product custody transfers.
  • The local smoke also queries n3x and DLMM state through view fn snapshots after the mutation flow and asserts the expected post-smoke multi-bin DLMM reserves, share supply, and guard config after a position add, fee collect, and partial LP withdrawal before writing deployments/local/smoke.latest.json.
  • In full scope, the local smoke also drives launchpad, referral, farms, automation, perps, options, and cover through their current lifecycle surfaces. Derivatives are no longer shell-view-only: perps covers open/funding/add-remove margin/close plus automatic queue/recover/requeue/liquidate, options covers shout buy-record-exercise plus outperformance buy-series settlement-exercise, and cover covers register-policy, stale/degraded reset handling, and claim routing, with typed view fn snapshots still recorded after the mutations.
  • make test-local-isolated is the safest end-to-end verifier when another local Nexus is already running, because it avoids the default tmp/iroha-localnet path and the default local ports while still proving the post-swap local contract state.
  • make test-local-foundation-isolated is the fastest isolated verifier for the current production target because it narrows the run to n3x plus DLMM and avoids unrelated downstream module bootstrap failures.
  • The canonical testnet smoke is signed and mutation-gated behind SORASWAP_ALLOW_TESTNET_MUTATIONS=1, while make smoke-testnet-readonly preserves the older readonly compatibility lane.
  • Mutating smoke steps require both a successful Torii submission and a committed transaction hash; read-only steps execute through /v1/contracts/view.
  • The current contract set is a real Kotodama foundation, not full product parity. Use the parity register before treating a module as production-complete.

About

SORASwap exchange for SORA Nexus

Resources

Readme

License

Apache-2.0 license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages