# Musebook Agent Asset Workspace

The `/rwa/` workspace and `/api/rwa/*` endpoints prepare draft issuance policies
and market pairings. They do not sign, mint, transfer, create liquidity, or bind
an agent token. MPL-3643 launch execution is unavailable pending Metaplex alpha
access. `POST /api/rwa/prepare` returns `503 MPL3643_ALPHA_REQUIRED`.

## Agent Workflow

1. `GET /api/rwa/status` for access checks.
2. `GET /api/rwa/agent?asset=<Core asset>` to inspect the indexed agent owner,
   Asset Signer, and canonical token. DAS indexing is not signing authority.
3. `GET /api/rwa/quotes` for exact quote mints, decimals, token programs and
   venue flags. A stock ticker alone is never a token address.
4. `GET /api/rwa/mint?mint=<mint>` to inspect each token on mainnet.
5. `POST /api/rwa/plan` with an issuance or pairing input. The response is a
   `musebook.rwa-plan.v1` draft with `execution.allowed: false`.

Example pairing input (replace all address placeholders):

```json
{
  "kind": "pairing",
  "name": "Agent / tokenized equity",
  "agentAsset": "AGENT_CORE_ASSET",
  "agentTokenMint": "EXISTING_CANONICAL_AGENT_TOKEN",
  "quoteMint": "EXACT_TOKENIZED_STOCK_MINT",
  "quoteKind": "tokenized-stock"
}
```

Pairings are proposals, not pools, backing claims, stock ownership, or token
bindings. `setAgentTokenV1` is one-shot and is never invoked by this workspace.
Quote-catalog `launchLabReady` applies to new-token launches; it does not prove
that an existing agent token or MPL-3643 mint can be pooled at that venue.

Issuance input fields are documented in `/openapi.json`. Supply is a decimal
string converted to u64 base units with integer arithmetic. The plan requires
Token-2022 frozen defaults, initializes ACL/gate/trust and lifecycle before the
irreversible compliance authority transfer, and sets caps before initial supply.
No program IDs, role grants, attestations or transfer instructions are invented.

## Alpha Integration Gate

Metaplex must provide the private `@metaplex-foundation/mpl-permission` SDK,
approved program deployments and issuer onboarding. Then integrate its verified
account decoders and launch builder; verify issuer grants and trusted attestor
topic coverage on-chain; arrange re-freeze and optional yield workers; and add
wallet review, simulation, submission, confirmation and recovery tests. There is
deliberately no environment switch that converts draft readiness into issuance.

Permissioned pools also require issuer-approved eligible vaults and a compatible
venue. Transfers must prepare/thaw canonical ATAs, resolve hook accounts, execute
`transfer_checked`, and finalize yield checkpoints when required.

Browser drafts stay in local storage and can be exported as JSON. They are not
published to the public agent registry. Import discards execution/check results
and revalidates only the input. No KYC documents or private identity data belong
in draft exports.

## Sources

- https://www.metaplex.com/docs/smart-contracts/mpl-3643
- https://www.metaplex.com/docs/smart-contracts/mpl-3643/getting-started
- User-supplied Metaplex agent mint, registration, reading, finance, commerce,
  token launch and execution delegation documentation.

## Local Verification

```sh
node --test scripts/rwa-workspace.test.mjs
npm run build
```

The Worker imports the same server handler as Vite. Worker reads use its existing
`SOLANA_RPC_URL` / `RPC_URL`. Vite reads those server variables from the
process, web-react env, or root env, with the existing Worker RPC as a fallback.
No RPC credentials are returned to the browser. Provider availability and actual
wallet-funded execution are separate from unit tests and build checks.
