# Commands #
Version 0.9.1-20190822.
net2o separates data and commands. Data is passed through to higher
layers, commands are interpreted when they arrive. For connection
requests, a special bit is set, and the address then isn't used as
address, but as IV for the opportunistic encoding.
The command interpreter is a stack machine with two data types: 64
bit integers and strings (floats are also suppored, but used
infrequently). Encoding of commands, integers and string length
follows protobuf conceptually (but MSB first, not LSB first as with
protobuf, to simplify scanning), strings are just sequences of
bytes (interpretation can vary). Command blocks contain a sequence
of commands; there are no conditionals and looping instructions.
Strings can contain encrypted nested commands, used during
communication setup.
## List of Commands ##
Commands are context-sensitive in an OOP method hierarchy sense.
### base commands ###
* $0 end-cmd ( -- )
end command buffer
* $1 lit ( #u -- u )
literal
* $2 -lit ( #n -- n )
negative literal, inverted encoded
* $3 string ( #string -- $:string )
string literal
* $4 flit ( #dfloat -- r )
double float literal
* $5 end-with ( o:object -- )
end scope
* $6 oswap ( o:nest o:current -- o:current o:nest )
* $7 tru ( -- f:true )
true flag literal
* $8 fals ( -- f:false )
false flag literal
* $9 words ( ustart -- )
reflection
* $A nestsig ( $:cmd+sig -- )
check sig+nest
* $B secstring ( #string -- $:string )
secret string literal
* $C nop ( -- )
do nothing
* $D 4cc ( #3letter -- )
At the beginning of a file, this can be used as FourCC code
* $E padding ( #len -- )
add padding to align fields
* $F version ( $:version -- )
version check
### reply commands ###
* $10 push' ( #cmd -- )
push command into answer packet
* $11 push-lit ( u -- )
push unsigned literal into answer packet
* $13 push-$ ( $:string -- )
push string into answer packet
* $14 push-float ( r -- )
push floating point number
* $15 ok ( utag -- )
tagged response
* $16 ok? ( utag -- )
request tagged response
* $17 ko ( uerror -- )
receive error message
* $18 nest ( $:string -- )
nested (self-encrypted) command
* $19 token ( $:token n -- )
generic inspection token
* $1A error-id ( $:errorid -- )
error-id string
* $1B version? ( $:version -- )
version cross-check
### connection generic commands ###
* $20 request-done ( ureq -- )
signal request is completed
* $21 set-cookie ( utimestamp -- )
cookies and round trip delays
* $22 punch-load, ( $:string -- )
use for punch payload: nest it
* $23 punch ( $:string -- )
punch NAT traversal hole
* $24 punch-done ( -- )
punch received
### connection setup commands ###
* $30 tmpnest ( $:string -- )
nested (temporary encrypted) command
* $31 encnest ( $:string -- )
nested (completely encrypted) command
* $32 close-tmpnest ( -- )
cose a opened tmpnest, and add the necessary stuff
* $33 close-encnest ( -- )
cose a opened encnest, and add the necessary stuff
* $34 new-data ( addr addr u -- )
create new data mapping
* $35 new-code ( addr addr u -- )
crate new code mapping
* $36 store-key ( $:string -- )
store key
* $37 map-request ( addrs ucode udata -- )
request mapping
* $38 set-tick ( uticks -- )
adjust time
* $39 get-tick ( -- )
request time adjust
* $3A receive-tmpkey ( $:key -- )
receive emphemeral key
* $3B tmpkey-request ( -- )
request ephemeral key
* $3C keypair ( $:yourkey $:mykey -- )
select a pubkey
* $3D update-key ( -- )
update secrets
* $3E gen-ivs ( $:string -- )
generate IVs
* $3F addr-key! ( $:string -- )
set key for reply
* $40 punch? ( -- )
Request punch addresses
* $41 >time-offset ( n -- )
set time offset
* $42 context ( -- )
make context active
* $43 gen-reply ( -- )
generate a key request reply
* $44 gen-punch-reply ( -- )
* $45 invite ( $:nick+sig $:pk -- )
invite someone
* $46 request-invitation ( -- )
ask for an invitation as second stage of invitation handshake
* $47 sign-invite ( $:signature -- )
send you a signature
* $48 request-qr-invitation ( -- )
ask for an invitation as second stage of invitation handshake
* $49 tmp-secret, ( -- )
* $4A qr-challenge ( $:challenge $:respose -- )
* $4B invite-result ( flag -- )
### connection commands ###
* $25 disconnect ( -- )
close connection
* $26 set-ip ( $:string -- )
set address information
* $27 get-ip ( -- )
request address information
* $28 set-blocksize ( n -- )
set blocksize to 2^n
* $29 set-blockalign ( n -- )
set block alignment to 2^n
* $2A close-all ( -- )
close all files
* $2B set-top ( utop flag -- )
set top, flag is true when all data is sent
* $2C slurp ( -- )
slurp in tracked files
* $2D ack-reset ( -- )
reset ack state
### file commands ###
* $30 file-id ( uid -- o:file )
choose a file object
* $20 open-file ( $:string mode -- )
open file with mode
* $21 file-type ( n -- )
choose file type
* $22 close-file ( -- )
close file
* $23 set-size ( size -- )
set size attribute of current file
* $24 set-seek ( useek -- )
set seek attribute of current file
* $25 set-limit ( ulimit -- )
set limit attribute of current file
* $26 set-stat ( umtime umod -- )
set time and mode of current file
* $27 get-size ( -- )
request file size
* $28 get-stat ( -- )
request stat of current file
* $29 set-form ( w h -- )
if file is a terminal, set size
* $2A get-form ( -- )
if file is a terminal, request size
* $2B poll-request ( ulimit -- )
poll a file to check for size changes
### ack commands ###
* $31 ack ( -- o:acko )
ack object
* $20 ack-addrtime ( utime addr -- )
packet at addr received at time
* $21 ack-resend ( flag -- )
set resend toggle flag
* $22 set-rate ( urate udelta-t -- )
set rate
* $23 resend-mask ( addr umask -- )
resend mask blocks starting at addr
* $24 track-timing ( -- )
track timing
* $25 rec-timing ( $:string -- )
recorded timing
* $26 send-timing ( -- )
request recorded timing
* $27 ack-b2btime ( utime addr -- )
burst-to-burst time at packet addr
* $28 ack-resend# ( addr $:string -- )
resend numbers
* $29 ack-flush ( addr -- )
flushed to addr
* $2C set-rtdelay ( ticks -- )
set round trip delay only
* $2D seq# ( n -- )
set the ack number and check for smaller
### log commands ###
* $19 log-token ( $:token n -- )
* $20 emit ( utf8 -- )
emit character on server log
* $21 type ( $:string -- )
type string on server log
* $22 cr ( -- )
newline on server log
* $23 . ( n -- )
print number on server log
* $24 f. ( r -- )
print fp number on server log
* $25 .time ( -- )
print timer to server log
* $26 !time ( -- )
start timer
* $32 log ( -- o:log )
free all parts of the subkey
### key storage commands ###
* $2 slit ( #lit -- )
deprecated slit version
* $F kversion ( $:string -- )
key version
* $11 privkey ( $:string -- )
private key
* $12 keytype ( n -- )
key type (0: anon, 1: user, 2: group)
* $13 keynick ( $:string -- )
key nick
* $14 keyprofile ( $:string -- )
key profile (hash of a resource)
* $15 keymask ( x -- )
key access right mask
* $16 keygroups ( $:groups -- )
access groups
* $17 +keysig ( $:string -- )
add a key signature
* $18 keyimport ( n -- )
* $19 rskkey ( $:string --- )
revoke key, temporarily stored
* $1A keypet ( $:string -- )
* $1B walletkey ( $:seed -- )
* $1C avatar ( $:string -- )
key avatar profile (hash of a resource)
* $1D key-string1 ( $:string -- )
* $1E key-string2 ( $:string -- )
* $1F key-string3 ( $:string -- )
* $20 key-string4 ( $:string -- )
* $21 key-sec1 ( $:string -- )
* $22 key-sec2 ( $:string -- )
* $23 key-num1 ( 64n -- )
* $24 key-num2 ( 64n -- )
* $25 key-num3 ( 64n -- )
* $26 key-num4 ( 64n -- )
read a nested key into sample-key
### address commands ###
* $11 addr-pri# ( n -- )
priority
* $12 addr-id ( $:id -- )
unique host id string
* $13 addr-anchor ( $:pubkey -- )
anchor for routing further
* $14 addr-ipv4 ( n -- )
ip address
* $15 addr-ipv6 ( $:ipv6 -- )
ipv6 address
* $16 addr-portv4 ( n -- )
ipv4 port
* $17 addr-portv6 ( n -- )
ipv6 port
* $18 addr-port ( n -- )
ip port, both protocols
* $19 addr-route ( $:net2o -- )
net2o routing part
* $1A addr-key ( $:addr -- )
key for connection setup
* $1B addr-revoke ( $:revoke -- )
revocation info
* $1C addr-ekey ( $:ekey -- )
ephemeral key
### dht commands ###
* $33 dht-id ( $:string -- o:o )
set DHT id for further operations on it
* $20 dht-host+ ( $:string -- )
add host to DHT
* $21 dht-host- ( $:string -- )
delete host from DHT
* $22 dht-host? ( -- )
query DHT host
* $23 dht-tags+ ( $:string -- )
add tags to DHT
* $24 dht-tags- ( $:string -- )
delete tags from DHT
* $25 dht-tags? ( -- )
query DHT tags
* $26 dht-owner+ ( $:string -- )
add owner to DHT
* $27 dht-owner- ( $:string -- )
delete owner from DHT
* $28 dht-owner? ( -- )
query DHT owner
* $29 dht-have+ ( $:string -- )
add have to DHT
* $2A dht-have- ( $:string -- )
delete have from DHT
* $2B dht-have? ( -- )
query DHT have
### vault commands ###
* $20 dhe ( $:pubkey -- )
start diffie hellman exchange
* $21 vault-keys ( $:keys -- )
vault keys can be opened with the dhe secret; each key is IV+session key+checksum
* $22 vault-file ( $:content -- )
this is the actual content of the vault
if blockwise, there may be multiple parts
* $23 vault-sig ( $:sig -- )
the signature of the vault, using the keyed hash over the file
* $24 vault-crypt ( n -- )
set encryption mode and key wrap size
* $25 vault-auth ( $:auth -- )
block authentication, 64 byte block
* $26 vault-dhe-keys ( $:dhe+keys -- )
### message commands ###
* $20 msg-start ( $:pksig -- )
start message
* $21 msg-tag ( $:tag -- )
tagging (can be anywhere)
* $22 msg-id ( $:id -- )
a hash id
* $23 msg-chain ( $:dates,sighash -- )
chained to message[s]
* $24 msg-signal ( $:pubkey -- )
signal message to one person
* $25 msg-re ( $:hash )
relate to some object
* $26 msg-text ( $:msg -- )
specify message string
* $27 msg-object ( $:object type -- )
specify an object, e.g. an image
* $28 msg-action ( $:msg -- )
specify action string
* $29 msg-payment ( $:contract -- )
payment transaction
* $2A msg-otrify ( $:date+sig $:newdate+sig -- )
turn a past message into OTR
* $2B msg-coord ( $:gps -- )
GPS coordinates
* $2C msg-url ( $:url -- )
specify message URL
* $2D msg-like ( xchar -- )
add a like
* $2E msg-lock ( $:key -- )
lock down communciation
* $2F msg-unlock ( -- )
unlock communication
* $30 msg-perms ( $:pk perm -- )
permissions
### group description commands ###
* $20 group-name ( $:name -- )
group symbolic name
* $21 group-id ( $:group -- )
group id, is a pubkey
* $22 group-member ( $:memberkey -- )
add member key
* $23 group-admin ( $:adminkey -- )
set admin key
* $24 group-perms ( 64u -- )
permission/modes bitmask
### messaging commands ###
* $34 message ( -- o:msg )
push a message object
* $21 msg-group ( $:group -- )
set group
* $22 msg-join ( $:group -- )
join a chat group
* $23 msg-leave ( $:group -- )
leave a chat group
* $24 msg-reconnect ( $:pubkey+addr -- )
rewire distribution tree
* $25 msg-last? ( start end n -- )
* $26 msg-last ( $:[tick0,msgs,..tickn] n -- )
* $A msg-nestsig ( $:cmd+sig -- )
check sig+nest
### DVCS patch commands ###
DVCS metadata is stored in messages, containing message text, refs
and patchset objects. Patchset objects are constructed in a way
that makes identical transactions have the same hash.
* $20 dvcs-read ( $:hash -- )
read in an object
* $21 dvcs-rm ( $:hash+name -- )
delete file
* $22 dvcs-rmdir ( $:name -- )
delete directory
* $23 dvcs-patch ( $:diff len -- )
apply patch, len is the size of the result
* $24 dvcs-write ( $:perm+name size -- )
write out file
* $25 dvcs-unzip ( $:diffgz size algo -- $:diff )
unzip an object
* $26 dvcs-ref ( $:hash+perm+name -- )
external hash reference
### payment commands ###
* $20 pay-source ( $:source -- )
source, pk[+hash] for lookup
* $21 pay-sink ( n $:sig -- )
sink, signature
* $22 pay-asset ( asset -- )
select global asset type
* $23 pay-obligation ( $:enc-asset -- )
select per-contract obligation
* $24 pay-amount ( 64amount -- )
add/subtract amount to current asset
* $25 pay-damount ( 128amount -- )
add/subtract 128 bit amount
* $26 pay-comment ( $:enc-comment -- )
comment, encrypted for selected key
* $27 pay-balance ( u -- )
select&balance asset
* $28 pay-#source ( u -- )
select source
### Contracts ###
Contracts are state changes to wallets. A serialized wallet is a contract
that contains all the changes from an empty wallet to fill it; it is not
checked for balance.
A dumb contract is checked for balance. It consists of several selectors
(source/account, asset), transactions (amounts added or subtracted from an
asset), comments (encoded for the receiver, with a ephermeral pubkey as
start and a HMAC as end). Comments are fixed 64 bytes, either plain text or
hashes to files. Transactions have to balance, which is facilitated with
the balance command, which balances the selected asset.
The signature of a contract signs the wallet's state (serialized in
normalized form) after the contract has been executed. The current
contract's hash is part of the serialization.