@flapsdk/vault-runtime
Generated from flap-vault-ui-template.
This package is the shared runtime surface that local preview, Artifact Workbench, and flap.sh should agree on.
Package version: 0.1.42. Source commit: 686934578ec40aec418484e7c1dac1f6782d598e.
Exports
./sdk: component-facing SDK hooks, helpers, types, and local oracle reader helper./ui: shared UI primitives./host: host-only provider, runtime preflight helpers and the browser-safe same-origin presentation fetcher./server: server-side presentation, runtime oracle-registry helpers, controlled image/text upload handler, and the Vault V2 NFT metadata/media resolver
See runtime-contract.json for the machine-readable subpath contract.
Mini App subroutes
Standalone Mini Apps use useMiniAppRouter() from ./sdk. It returns
App-relative pathname, decoded segments, search, and
push(path), replace(path), back(). Paths start with /
inside the current App; external URLs, traversal, encoded separators and hashes
are rejected. Routing grants no wallet or contract access.
MINI_APP_ROUTING_VERSION = 1 and sdkFeatures.miniAppRouting = 1
identify the feature. Hosts inject a router into MiniAppRuntimeProvider;
./host exports parseMiniAppPath, createMiniAppMemoryRouter and
createMiniAppBrowserRouter. Old Apps need no adapter. The new hook fails
explicitly if the host has not enabled routing. Deploy supporting hosts before
accepting new route-dependent artifacts; source-package provenance is unchanged.
FSI queries
Declare the intended FSI root in manifest.endpoints to use
sdk.readFsi(relativePath, params). Supported roots, in selection order, are
https://fsi.taxed.fun/fsi/v1, https://bsc-debug.butterfly.army/fsi/v1
and BSC Testnet https://bsc-testnet-debug.butterfly.army/fsi/v1.
When multiple roots are declared, this order applies regardless of array order
or chainId. Testnet packages should declare only the testnet FSI root.
Failed requests never fall back to another host. Exact reviewed root declarations,
HTTPS origin/path boundaries, GET, credential and redirect restrictions remain.
Hosts and Workbench must deploy a release containing the selected endpoint policy
and synchronize the Workbench source checker before accepting those packages.
Transaction confirmation
waitForTx(hash) polls the original transaction hash through the public client selected for that operation. It queries immediately, then every 2 seconds after a pending or transient-error response, with an 8-second deadline per query and a 180-second total deadline. It returns the original success/reverted status; applications must check status === "success" before showing success or refreshing as successful. A timeout means the result is unknown: retain the hash and reconcile it before offering another transaction. Polling does not follow sped-up or cancelled replacement transactions; the original hash can time out. The public API and receipt fields remain compatible.
taxed.fun source-checker compatibility
The official template source for stable 0.1.40 adds reviewed native-fetch
queries on every valid strict taxed.fun subdomain, including multi-level
subdomains. Hosts and paths must stay literal, query values must use the global
encodeURIComponent, and manifest endpoint declarations and safe GET options
remain required. The apex domain, dynamic hosts/paths and unsafe options do not
gain permission. Existing sdk.readFsi routing and the SDK exports are unchanged.
The source checker is not shipped in this npm package. Deploy the matching template and Workbench checker policies separately; upgrading this package alone does not enable the new native-fetch policy or approve an endpoint. See the 0.1.40 release guide and request policy.
Shared Vault UI and Mini App v2
This shared runtime supports standalone App wallet operations through
useFlapSdk({ chainId }) and the host-owned CopyButton from ./ui.
Vault UI keeps useFlapSdk() and its token-bound context. Both use this one
package; existing token-bound Mini Apps remain compatible.
Stable development uses the official main template and npm latest.
The shared CopyButton copies up to 1,048,576 UTF-16 code units without truncation.
Dynamic IPFS content
Stable runtime 0.1.37 introduces sdk.readIpfsText(cid, path?), which returns
UTF-8 text or JSON as a string, and IpfsText for escaped plain-text display.
IpfsImage accepts dynamic bare CIDs from FSI, contract state, or SDK uploads.
The SDK exports IPFS_CONTENT_VERSION = 1; the runtime contract advertises
sdkFeatures.ipfsContent = 1. Stable 0.1.36 lacks the text API/component.
Vault source keeps the @/src/sdk and @/src/ui authoring aliases. Obtain
sdk with useFlapSdk(), then call the reader from an async effect or event
handler. Independent Mini App v2 uses useFlapSdk({ chainId: 56 });
its chain SDK exposes the same reader and reviewed readFsi API.
Import IpfsText and IpfsImage from the UI alias for rendering:
const body = await sdk.readIpfsText(textCid);
// Parse JSON only if the application expects JSON content.
const post = JSON.parse(await sdk.readIpfsText(jsonCid));
<IpfsText cid={item.textCid} fallback={i18n.t("contentLoading")} />
<IpfsImage cid={item.imageCid} alt={i18n.t("postImageAlt")} />
Use safe relative path values for directory CIDs, never a gateway URL or
ipfs:// URI. The runtime controls gateways and validates every CID/path.
Text reads omit credentials/referrers, reject redirects and HTML responses,
enforce UTF-8 and a 256 KiB limit, and have an 8-second network/body deadline
after acquiring an active slot. Reads are deduplicated, cached and concurrency
limited. IpfsText does not interpret HTML or Markdown. Localize loading/error
and alt text, and paginate feeds. IpfsBackground remains static CID-only.
Dynamic content sources require human review. Upgrade Workbench and Flap hosts to the published runtime and deploy Workbench's matching static checker before accepting new components. Reads use platform gateways without a new host route; uploads continue through the existing host-owned upload service. Automated upload fixtures are mocked and do not verify live gateway availability.
Source documentation: