BSV blockchainBSV blockchain

Request permissions and organize outputs

Group the outputs your app creates with baskets, tags and labels, and see which windows BSV Desktop shows the user. At the end, a standalone Node script has created two tagged outputs in a basket and listed them back by basket, tag and label. Use this when your app keeps its own outputs, such as tickets or receipts, and must tell them apart from the rest of the wallet.

Before you begin

You need Node.js 22 or newer and a testnet wallet in BSV Desktop with some test coins. Send a payment from a web app shows how to set one up. The example installs @bsv/sdk in its first step and is written against version 3.2.1.

How it works

A BRC-100 wallet such as BSV Desktop keeps every UTXOUnspent transaction output it owns, and an app asks the wallet to create and list them. Three fields let the app organize what it creates:

FieldApplies toSet withRead withWhat the user is asked
basketOne outputbasket on the output of createActionlistOutputs with basketA Basket Access Request, once per basket name
tagsOne outputtags on the output of createActionlistOutputs with tagsNothing
labelsThe whole transactionlabels on createActionlistActions with labelsA Protocol Access Request for each label, named action label <label>

A transaction that spends from the wallet also opens a Spending Request.

Each basket or label permission the user grants is stored by the wallet as a transaction of its own, which costs the user a network fee of about 120 to 170 satoshis in BSV Desktop 3.1.1.

Turn on the basket and label requests

BSV Desktop 3.1.1 shows only the Spending Request by default. To see the basket and label windows while you develop, switch them on:

In BSV Desktop, select Settings and open Advanced settings.

The Settings page of BSV Desktop with the Advanced settings entry highlighted under Network and connections

In Advanced settings, scroll to Permissions Configuration and select Show Advanced Settings.

The Permissions Configuration card at the bottom of Advanced settings, with the Show Advanced Settings link highlighted at its top right

Switch on Require permission for basket insertion and Require permission for basket listing under Basket Permissions.

Basket Permissions in Permissions Configuration, with the basket insertion and basket listing toggles highlighted
Switch on Require permission when applying action labels and Require permission when listing actions by label under Action & Label Permissions.

Select Save Permissions Configuration. BSV Desktop notes that changes require an app reload to take effect.

Action and Label Permissions with the two label toggles highlighted, and the Save Permissions Configuration button highlighted at the bottom right

Every user chooses these settings for their own wallet, so your app cannot assume which windows appear.

Organize outputs with baskets, tags and labels

Create the outputs with the three fields, then read them back with filters.

Create outputs in a basket

With the basket and label requests on, the first step is to create two outputs in one transaction and answer what BSV Desktop asks:

Install the SDK

In an empty folder, install the package:

npm install @bsv/sdk

Write the script

Create outputs.mjs in the same folder. The script connects to BSV Desktop and asks it to create two one satoshi outputs in the basket tickets:

outputs.mjs
import { WalletClient, Script } from '@bsv/sdk'

const wallet = new WalletClient('auto', 'tickets.localhost')
const lockingScript = Script.fromASM('OP_NOP').toHex()

const { txid } = await wallet.createAction({
  description: 'Create two tickets',
  labels: ['batch one'],
  outputs: [
    { satoshis: 1, lockingScript, outputDescription: 'Ticket A', basket: 'tickets', tags: ['vip', 'row a'] },
    { satoshis: 1, lockingScript, outputDescription: 'Ticket B', basket: 'tickets', tags: ['general', 'row a'] }
  ]
})

console.log({ txid })

The second argument of WalletClient is the originator, the name BSV Desktop shows to the user and the name every permission is stored under. In a browser the page origin is used. In Node you pass a name of your own, and without one the call fails. An output locked with OP_NOP has no spending condition, so anyone can spend it. Use the locking script your app needs in a real project.

Run the script

Run the script from the same folder:

node outputs.mjs

The script waits while BSV Desktop opens three windows, one after the other, and each one needs an answer.

Grant the basket access

BSV Desktop first opens a Basket Access Request for the app tickets.localhost and the basket tickets. The reason it shows is the description of the action. Select Grant Access.

The Basket Access Request window of BSV Desktop for the app tickets.localhost and the basket tickets, with the Grant Access button highlighted

Grant the label access

Next comes a Protocol Access Request for action label batch one, because each label is its own protocol permission. Select Grant Access.

The Protocol Access Request window for action label batch one, with the Grant Access button highlighted

Authorize the spending

The last window is a Spending Request. It shows the description Create two tickets and an amount that adds the two satoshis of the outputs to the network fee. Blockchain transactions are irreversible, so check the amount and select Authorize.

The Spending Request window for tickets.localhost, showing Create two tickets, 55 satoshis and the Authorize button highlighted

The script prints the transaction ID, shortened here:

{
  txid: '777a…d73b'
}

List the outputs

With the outputs in the wallet, the next step is to read them back by basket, tag and label. The three snippets share one file, list.mjs:

List by basket

Create list.mjs next to outputs.mjs. The limit and offset fields page through the result, and an offset of -1 reads from the newest output:

list.mjs
import { WalletClient } from '@bsv/sdk'

const wallet = new WalletClient('auto', 'tickets.localhost')

const result = await wallet.listOutputs({ basket: 'tickets', limit: 10 })

console.log(result)

The result has the count and one entry for each output. The outpoint is the transaction ID and the output index, shortened here:

{
  totalOutputs: 2,
  outputs: [
    { satoshis: 1, spendable: true, outpoint: '777a…d73b.2' },
    { satoshis: 1, spendable: true, outpoint: '777a…d73b.1' }
  ]
}

Filter by tag

Narrow the same call with tags, in the same file. With includeTags set, each output returns its own tags:

const vip = await wallet.listOutputs({
  basket: 'tickets',
  tags: ['vip'],
  includeTags: true
})

console.log(vip)

Only Ticket A carries vip, so totalOutputs is 1. Each output returns its own tags, shortened here:

{
  totalOutputs: 1,
  outputs: [
    { satoshis: 1, spendable: true, outpoint: '777a…d73b.1', tags: ['vip', 'row a'] }
  ]
}

With several tags, tagQueryMode decides the match. The value all keeps the outputs that carry every tag, and any, the default, keeps the outputs that carry at least one.

Filter by label

Labels belong to the transaction, so read them with listActions. With includeLabels set, each action returns its labels:

const batch = await wallet.listActions({
  labels: ['batch one'],
  includeLabels: true
})

console.log(batch)

The result has one action. Its satoshis is negative, because the transaction spent from the wallet, and its labels include batch one. The wallet adds labels of its own, such as admin originator tickets.localhost, and your app sees them. The result, shortened:

{
  totalActions: 1,
  actions: [
    {
      txid: '777a…d73b',
      satoshis: -55,
      labels: ['batch one', 'admin originator tickets.localhost', …]
    }
  ]
}

With several labels, labelQueryMode takes all or any and works like tagQueryMode.

Manage the permissions of the app

The user decides what an app may do, and the app can ask for its permissions one at a time or all together.

Review what the app may do

The user manages every grant in BSV Desktop, and your app can point to this screen when a request is denied:

In BSV Desktop, select Apps and then the Connected tab.

In the card of your app, select Access.

The Connected tab of Apps in BSV Desktop with the tickets.localhost card, the Connected tab highlighted and the Access button of the card highlighted

Open Protocols to see each label of the app as action label <label>.

The Access page of tickets.localhost with the Protocols tab highlighted, listing the protocol action label batch one with the scope only with this app

Open Baskets to see the baskets the app may use. Select the × next to a basket and confirm with Revoke. BSV Desktop records the revoke as a transaction with a network fee.

The Revoke Access confirmation of BSV Desktop with the Revoke button highlighted

Request all permissions at once

An app that needs a basket, several labels and a spending limit can ask for them in one window by declaring them in a manifest:

Declare the permissions

Serve a manifest.json from the root of the domain that hosts your app, so it is at https://YOUR_DOMAIN/manifest.json. Replace YOUR_DOMAIN with the HTTPS domain of your app. The wallet reads the metanet.groupPermissions object:

manifest.json
{
  "name": "Tickets",
  "short_name": "Tickets",
  "metanet": {
    "schemaVersion": 1,
    "groupPermissions": {
      "description": "Permissions the Tickets app needs",
      "spendingAuthorization": {
        "amount": 1000,
        "description": "Create tickets and pay the network fee"
      },
      "basketAccess": [
        { "basket": "tickets", "description": "Store the tickets" }
      ]
    }
  }
}

The amount is a monthly spending limit in satoshis, and the window shows only that amount. A description on a basket entry appears as the reason for that basket.

Open the app from that domain

Load your app from YOUR_DOMAIN and make the first call that needs one of the declared permissions. BSV Desktop opens one Select App Permissions window with the app name from the manifest. It lists every item that is not yet granted, each with a box that is ticked by default. The user can untick items before approving, and the call goes through only if the permission it needs is approved.

Troubleshooting

Call fails with HTTP status 400 #

The user denied a request, or the wallet refused the call. WalletClient shows only the status. The response of BSV Desktop carries the reason: Permission denied. for a denied basket, label or spending request, and The user has denied the request for permission. for a denied grouped request. A denial is not remembered, so the next call opens the window again.

Granted basket asks for permission again #

The wallet compares basket names exactly as typed. TICKETS, tickets with spaces around, and an empty name each open a new request. Use the same lower case name, with no spaces around it, in every call.

Reserved basket name is rejected #

The name default and any name that starts with admin are reserved for the wallet. The call fails at once with Basket "default" is admin-only. and no window opens. Pick another name.

Long basket name is rejected #

A long basket name fails with The tag parameter must be no more than 300 length. The usable limit is shorter than the 300 in the message, and the message says tag for a basket. Keep names short.

Script cannot find BSV Desktop #

A script that creates WalletClient without an originator fails with No wallet available over any communication substrate. even while BSV Desktop is open. Pass an originator as the second argument, as in the examples.

Next steps

With the outputs organized, move on to Mainnet or track your transactions with overlays: